# Writing a Sepale family

You are writing a **family** for Sepale: one CSS file that styles every
component of the kit in one visual direction, tuned through **parameters** a
theme sets. The components already exist: their DOM and their classes are
fixed. Your file paints them. Nothing you write changes the markup.

This document is self-contained and written for an AI assistant. It holds the
steps, the **contract** the file must meet, and links to one page per
component. Links are relative to this file's address.

- Every component in one file, for an upload: [full.md](full.md)
- The page that loads your file and reports on it: [Create a family](../new-family), in the app

## Steps

### 1. Agree the direction

Ask the user, in one message, for:

- the **name**: one lowercase word (the built families are flowers: daisy,
  dahlia, sunflower, cosmos, peony);
- the **direction**: what the look is, in a sentence or two, and the design
  system or site it follows, if any;
- the **parameters** they want to tune: colours at least, then the family's own
  knobs (radius, border width, shadow depth, blur…);
- the **light/dark** stance: both themes, or one.

Done when the user has confirmed a name and a direction. Write the direction
into the header comment (see *The file*), it is the brief for every step after.

### 2. Write the root

The header comment, the `uu-params` declaration, the defaults on
`:where(:root)`, then everything outside a component: the type scale,
`--scale`, the colours the family derives (inks written on each colour), the
recipes on `:where(*)`.

Done when the file loads on the app's page and the report shows the
parameters, with no error.

### 3. Style the components, one page at a time

Work through the [component index](#components) in its order: form controls
lean on buttons and inputs, layouts lean on everything. For each page:

1. Read its page here. It lists the component's classes (root, parts, axes,
   flags), the states the built families draw, the custom properties the
   component writes for you to read, and the DOM it renders.
2. Read the reference SCSS it links, for the **mechanism**: how the built
   families lay the component out, position its indicator, draw its fill. Its
   `structure` mixin is the mechanism to keep; its `look` mixin is the part you
   rewrite in your direction.
3. Write the component's rules.

Done for a page when every class it lists is styled or deliberately left out,
and every listed state has a visible answer: hover, focus-visible, disabled,
checked, open, current. Done for the step when the app's report lists no
missing component you meant to style.

### 4. Hand over and iterate

Give the user the whole file, every time: the app loads a file, not a patch.
They load it on the app's page (loading a file under the same name replaces the
family) and walk the component pages in a light and a dark theme.

Hand over the stylesheet only. Do NOT write a `.d.ts`, a type declaration or a
list of variants for it. The family works without one: the classes draw
everything. Its types — `name.css.d.ts`, which narrows the Svelte components'
props to what the family draws — are optional and DERIVED from the stylesheet:
the app's "Create a family" page offers them once the family is loaded
("Download types", or the bundle), and `npx sepale-types name.css` writes them
without the app. A declaration written by hand can promise a variant the
stylesheet does not draw; the derived one cannot. If the user asks for types,
point them to those, and tell them to regenerate after every change.

Each round, the user names what is wrong: a component, a state, a theme. Answer
with the smallest change that fixes it, in that component's rules only, and
say which rules you changed. When the report shows a class no component
classifies, rename or remove it before anything else: such a class is a typo or
an invention, and the build of a real family rejects it.

## The contract

### The file

One stylesheet, plain CSS, UTF-8, self-contained: no `@import`, and no `url()`
to another site. The app previews a family with everything remote blocked (its
security policy), so a remote font or image shows as missing there. Name a web
font in a parameter's value (`"Inter", system-ui, sans-serif`) and let the page
that uses the family load it; an icon or a texture goes inline, as a `data:`
URL.

It opens with a header comment, which the app reads for the family's name and
prose. Keep its shape:

```css
/* ============================================================
   STYLE FAMILY — « orchid »  (after Some Design System)

   One or two paragraphs: what the look is, what it follows.

   Changes made to fit our contract:
     - Each place where the source design had to be read rather
       than copied, one bullet each.
   ============================================================ */
```

The `(after …)` part is the short label the family picker shows. The
"Changes made" list is optional.

### Parameters

A parameter is a custom property a theme sets. Declare each one twice: its
default on `:where(:root)` (zero specificity, so any theme wins), and its
description in one `uu-params` comment, a JSON array on a single line, which the
theme editor reads:

```css
:where(:root) {
	--color-surface-1: #ffffff;
	--color-primary: #4f46e5;
	--radius-field: 0.5rem;
}

/*! uu-params [{"name":"color-surface-1","label":"Surface 1","group":"Colors","type":"color","value":"#ffffff","kind":"surface","on":"color-on-surface"},{"name":"color-primary","label":"Primary","group":"Colors","type":"color","value":"#4f46e5","kind":"accent","on":"color-on-primary"},{"name":"radius-field","label":"Field radius","group":"Shape","type":"length","value":"0.5rem","min":0,"max":2,"step":0.05,"unit":"rem","units":["px","rem","em"],"description":"Corner radius of buttons, inputs and selects."}] */
```

Fields: `name` (without `--`), `label`, `group`, `type`, `value` (the default),
and optionally `description`, `min` / `max` / `step` (a slider), `unit` and
`units` (a unit picker). `type` is one of:

- `color`;
- `length`, `number`;
- `edge-width`: a `border-width` shorthand, edited as a width and four edge
  toggles (`"1px 0 1px 0"` draws top and bottom);
- `shadows`: a whole `box-shadow` value, edited as layers.

A colour also carries `kind`, which is `surface` (a ground things rest on),
`accent` (a colour things are painted with) or `ink` (text and lines over both),
and `on`, the variable holding the ink written on it. Groups the editor orders
first: `Colors`, `Typography`, `Shape`, `Size`, `Effects`, `Elevation`.

The parameter set is the family's own: five surfaces or one, fifteen knobs or
none. The names the built families share (and that the colour axes expect) are
`--color-surface-1` … `-3`, `--color-border`, `--color-on-surface`, and the
eight accents `--color-primary`, `secondary`, `accent`, `neutral`, `info`,
`success`, `warning`, `error`, each with its ink `--color-on-<accent>`. An ink
may be a parameter or derived by the family in its root rules
(`color-mix`, `oklch`): derived inks make every theme legible.

A theme is a `:root { … }` block of parameter values and a `color-scheme`. The
family reads only its parameters, so a dark theme is a set of dark values, and
the same rules draw it.

### Sizing

Every component is **intrinsic**: its lengths are `em`, resolved against its
own font size, so a component grows with its text and needs no breakpoint.

- A **size** axis value only sets `--fontsize`. The type scale is fixed, ratio
  1.125 on `1rem`; declare it in the root as `--default-xxs` … `--default-xxxl`
  (`0.7023rem`, `0.7901rem`, `0.8889rem`, `1rem`, `1.125rem`, `1.2656rem`,
  `1.4238rem`, `1.6018rem`, `1.802rem`) and write
  `.btn-lg { --fontsize: var(--lg, var(--default-lg)); }`. The component reads
  `font-size: var(--fontsize, var(--default-base))`.
- **`--scale`** (default `1`, on `:where(:root)`) grows the frame and never the
  text: write each height, padding and gap as `calc(Nem * var(--scale))`. Text,
  icons, radii and hairlines stay out of it.
- Inline SVG sits on the text: `svg { height: 1em; }`.
- The root font size is the page's. The family leaves it alone.

### Slots and recipes

- **Fill slots.** A component's base rule paints from its own custom
  properties (`background-color: var(--btn-bg)`, `color: var(--btn-fg)`), and
  every variant sets those properties. Variants then compose, and integrations
  keep working: `join` rounds the outer corners of its children through
  `--join-ss`, `--join-se`, `--join-es`, `--join-ee`, which a field or a button
  reads as `border-start-start-radius: var(--join-ss, var(--radius-field))`.
- **Give every `var()` a value.** A `var()` that resolves to nothing voids the
  whole declaration: `border: var(--border) solid red` with `--border` unset
  draws no border at all.
- **Recipes on `:where(*)`.** A formula built from other custom properties (a
  shadow from a depth, a relief from an offset) is declared on `:where(*)`, so
  it resolves on each element and recomputes when a state changes one input. On
  `:root` it would resolve once, for the whole page.
- **Write class names whole** in selectors (`.btn-primary`), never assembled.

### Classes and states

- Write the classes the component pages list, under their namespaces: `btn`
  owns `.btn` and every `.btn-*`. A class outside every list is one no
  component writes, and the app reports it.
- A family may ship part of an axis (four colours instead of eight) or leave a
  component out: the components then offer only what the family ships, and the
  app reports what is missing. Ship whole components rather than half of one.
- Reach into another component where the two meet (`join` sets `.btn`'s
  corners, `validator` colours a field): that is integration, and it lives in
  the file of the component doing the reaching.
- Draw the **states** each page lists: they are how the DOM says what it is
  (`[aria-selected=true]`, `[data-state=peek]`, `:checked`, `[open]`). Draw
  `:focus-visible` on everything focusable.
- Read the **custom properties the component writes**, listed on each page:
  the tab indicator's position (`--tabs-x` …), a range's fill (`--range-pct`),
  a one-off fill set by the `background` prop (`--<namespace>-bg`).

### Motion

- **What moves on a change of state is the family's**: CSS transitions and
  keyframes on its classes and states. A menu folding, a knob sliding, the tab
  indicator following `--tabs-x`: the component sets a state or a custom
  property, the family decides how it travels.
- **No component animates by itself** (ADR 0019). When an element comes,
  goes or changes places, the component marks the moment on it and waits as
  long as the family's CSS says, read back from the computed style:
  - `data-motion="enter"`: just inserted, while your animation runs. A new
    element has no style to transition from: use `@keyframes` (or
    `@starting-style`).
  - `data-motion="leave"`: going; it stays in the DOM until your transitions
    and animations on it have run (a dialog's box, a dropdown, a dismissed
    alert, a toast).
  - `data-motion="move"`: changed places in a list (the toast stack);
    `--motion-dx` / `--motion-dy` hold where it came from.
  - `--motion-w` / `--motion-h`: its size as it enters or leaves, for a
    height that folds (`height: auto` does not animate).
  Draw nothing for a phase and it is instant. Each page's *Motion* section
  names the elements marked.
- **Some wait for a change of state**: a drawer closes its `<dialog>` once its
  hidden state's transition has run; a ripple wave is removed once its
  animation has.
- Wrap what is decorative in `@media (prefers-reduced-motion: no-preference)`,
  or cut it under `reduce`.

### Browser support

Target at least 90% of browsers in use: `color-mix`, `oklch`, `:has()`,
`:where()`, container queries and `@layer` qualify. Give anything newer a
fallback declared before it.

## Reference

The five built families, as SCSS, one file per component:
`reference/<family>/<page>.scss`, where `<family>` is `daisy` (after DaisyUI),
`dahlia` (after Radix), `sunflower` (neo-brutalist), `cosmos` (hand-drawn) or
`peony` (soft dashboard). Each family's `reference/<family>/index.scss` holds its
parameters and include order, `reference/<family>/_root.scss` its page layer.
The Sass helpers they call are in `reference/_mixins.scss`, `_config.scss`
(the axis lists) and `_params.scss` (the `uu-params` emitter). Each file has a
`structure` mixin (the mechanism) and a `look` mixin (the values): read them for
how a component works, then write your own CSS.

## Components

### Actions

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Button](button.md) | `btn` | `<Button>` | The thing you press. |
| [Link](link.md) | `link` | — | Text that goes somewhere. |
| [Join](join.md) | `join` | `<Join>` | Glue two or more controls into one object: the inner corners go square, the outer ones keep the family's radius. |

### Form

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Input](input.md) | `input` | `<Input>` | A single-line field. |
| [Textarea](textarea.md) | `textarea` | `<Textarea>` | A multi-line field. |
| [Select](select.md) | `select` | `<Select>` | A closed list of choices, drawn as a field so it lines up with the inputs beside it. |
| [Combobox](combobox.md) | `combobox` | `<Combobox>` | A field whose value is looked up in a list while typing. |
| [Number input](number-input.md) | `number-input` | `<NumberInput>` | A number field, its figure aligned to the end like a number in a column. |
| [Date picker](date-picker.md) | none | — | A field that opens a calendar: an Input, a Dropdown and an inline Calendar put together. |
| [Calendar](calendar.md) | `calendar` | `<Calendar>` | A date picker, drawn by air-datepicker (vendored, MIT). |
| [Color picker](color-picker.md) | `color-picker` | `<ColorPicker>` | One colour, edited in OKLCH: lightness, chroma and hue, each a slider whose track is the gradient it moves along, plus the raw value for anything the sliders cannot say. |
| [File input](file-input.md) | `file-input` | `<FileInput>` | The browser's file picker wearing the kit's field frame. |
| [File dropzone](file-dropzone.md) | none | — | Its content becomes a place to drop files on. |
| [Checkbox](checkbox.md) | `checkbox` | `<Checkbox>` | An independent yes/no. |
| [Radio](radio.md) | `radio` | `<Radio>` | One choice out of several. |
| [Toggle](toggle.md) | `toggle` | `<Toggle>` | A switch that takes effect immediately, unlike a checkbox that waits for a submit. |
| [Switch](switch.md) | `switch` | `<Switch>` | One choice among a few, as a pill track. |
| [Range](range.md) | `range` | `<Range>` | A value picked along a track, where the approximate position matters more than the number. |
| [Rating](rating.md) | `rating` | `<Rating>` | A whole-number score picked from a row of icons. |
| [Chips input](chips-input.md) | `chips-input` | `<ChipsInput>` | An accumulator: several values, each a chip, collected from a field. |
| [Editable](editable.md) | `editable` | `<Editable>` | A value shown as it is, that turns into its editor when asked: a click, Enter or F2. |

### Form layout

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Label](label.md) | `label` | `<Label>` | Inline text naming a control — on its own, or inside a field as a prefix or a suffix (.input > .label). |
| [Floating label](floating-label.md) | `floating-label` | `<FloatingLabel>` | A container that wraps a field: its <span> sits over the frame and rises out of the way once the field has content. |
| [Fieldset](fieldset.md) | `fieldset` | `<Fieldset>` | A group of related fields with a legend. |
| [Validator](validator.md) | `validator` | — | Marks a field as validated: the field paints itself from its own :valid / :invalid state, and the hint appears only when it is wrong. |

### Display

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Text](text.md) | `text` `title` `subtitle` | `<Subtitle>` `<Text>` `<Title>` | The typographic scale, delivered as classes — no frame, no state. |
| [Avatar](avatar.md) | `avatar` | `<Avatar>` | A picture, or a few letters, standing for someone — cropped to a shape. |
| [Badge](badge.md) | `badge` | `<Badge>` | A count or a mark pinned to another element. |
| [Chip](chip.md) | `chip` | `<Chip>` | A small standalone token: a status, a tag, a removable value. |
| [Swatch](swatch.md) | `swatch` | `<Swatch>` | A sample of one colour, passed in as --swatch-color. |
| [Bubble](bubble.md) | `bubble` | `<Bubble>` | A chat message: one class on one block, which gives it a fill, an ink and a tail at the bottom of one side. |
| [Card](card.md) | `card` | `<Card>` | A box with, optionally, a figure, a title, a body and a row of actions. |
| [Stat](stat.md) | `stat` `stats` | `<Stat>` `<Stats>` | A figure worth a glance — a title, a value, a description, and optionally a figure on the side and actions. |
| [Carousel](carousel.md) | `carousel` | `<Carousel>` | A row of items that scrolls and snaps natively, with optional arrows over it, upcoming items and a pagination under it. |

### Feedback

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Alert](alert.md) | `alert` | `<Alert>` | An inline message — information, success, warning, error — where it concerns the user. |
| [Toast](toast.md) | `toast` | `<Toast>` | A stack of alerts that pile up, each leaving on its own. |
| [Loading](loading.md) | `loading` | `<Loading>` | Work is in progress and there is no percentage to show. |
| [Progress](progress.md) | `progress` | `<Progress>` | How far along something is, on a line. |
| [Radial progress](radial-progress.md) | `radial-progress` | `<RadialProgress>` | The same statement as progress, drawn as a ring, for when the number itself is the point. |
| [Skeleton](skeleton.md) | `skeleton` | `<Skeleton>` | The shape of content that has not arrived. |
| [Empty state](empty-state.md) | `empty-state` | `<EmptyState>` | What to show when there is nothing: no results, an empty folder, a list not started yet. |

### Data

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Data handler](data-handler.md) | none | — | The live state of one remote resource — the current page of rows, the total, the search, the sort, the filters, the selection, the unsaved edits and their history — and the requests that read and change it. |
| [Data control](data-control.md) | `data-control` | `<DataControl>` | The controls of a data handler, around the view that shows its rows: filters, sort, search, page size, pagination, and actions on the selection or on the whole resource. |
| [Table](table.md) | `table` | `<Table>` | A real <table>. |
| [Grid](grid.md) | `grid` | `<Grid>` | Items in as many columns as fit. |
| [List](list.md) | `list` | `<List>` | Rows of data in a painted box. |
| [Kanban](kanban.md) | `kanban` | `<Kanban>` | Items in columns, one column per state they can be in. |
| [File explorer](file-explorer.md) | `file-explorer` | `<FileExplorer>` | Files and folders in a hierarchy, Drive-like: the folder tree, the current folder as a list or a grid, the details of the selection, under a toolbar with the path and your actions. |

### Navigation

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Menu](menu.md) | `menu` | `<Menu>` | Navigation with one current item, optional section titles and optional nested groups. |
| [Tabs](tabs.md) | `tabs` | `<Tabs>` | Switching which panel is visible. |
| [Breadcrumbs](breadcrumbs.md) | `breadcrumbs` | `<Breadcrumbs>` | Where you are in a hierarchy, and the way back up. |
| [Steps](steps.md) | `steps` | `<Steps>` | Where the user is in a journey: one column per step, one bar per sub-step. |
| [Pagination](pagination.md) | `pagination` | `<Pagination>` | A row of pages to jump between, with previous / next. |
| [Dock](dock.md) | `dock` | `<Dock>` | A bar pinned to the bottom edge, for the two to five places you go most. |

### Layout

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Navbar](navbar.md) | `navbar` | `<Navbar>` | A bar across the top. |
| [Sidebar](sidebar.md) | `sidebar` | `<Sidebar>` | An app's side column — a brand, a menu, an account — that folds to a rail. |
| [Drawer](drawer.md) | `drawer` | `<Drawer>` | A panel sliding in from any side, in three states: hidden, peek (its last --drawer-peek in view) and open (all --drawer-size of it). |
| [Footer](footer.md) | `footer` | `<Footer>` | The closing block of a page: columns of links that fill the width as room allows, then a bottom row. |
| [Hero](hero.md) | `hero` | `<Hero>` | The large opening block of a page: a title, a sentence, a call to action, and optionally media beside them. |
| [Divider](divider.md) | `divider` | `<Divider>` | A rule between two things, horizontal or vertical, optionally carrying a word or two. |
| [Collapse](collapse.md) | `collapse` | `<Collapse>` | A panel that folds under its trigger. |
| [Accordion](accordion.md) | `accordion` | `<Accordion>` | A stack of Collapses, joined at their edges. |

### Overlay

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Dialog](dialog.md) | `dialog` | `<Dialog>` | A box laid over the page, built on the native <dialog>. |
| [Dropdown](dropdown.md) | `dropdown` | `<Dropdown>` | A trigger and a box that floats next to it — a menu, a filter, a small form. |
| [Tooltip](tooltip.md) | `tooltip` | `<Tooltip>` | A short hint beside its trigger, shown on hover and on keyboard focus. |

### Mockups

| Page | Namespaces | Svelte | What it is |
| --- | --- | --- | --- |
| [Mobile frame](mobile-frame.md) | `mobile-frame` | `<MobileFrame>` | A phone drawn around content, for showcases and screenshots — not an emulator. |
| [Window frame](window-frame.md) | `window-frame` | `<WindowFrame>` | An application window drawn around content: a title bar with three controls, a title and actions, above a body that scrolls. |
| [Laptop frame](laptop-frame.md) | `laptop-frame` | `<LaptopFrame>` | A laptop drawn around content: a lid holding a 16:10 screen that scrolls, on a wider base. |
