@misoto22/design 0.5.0 → 0.6.0

package/skills/misoto22-design/rules/a11y.md

@@ -0,0 +1,115 @@
+# Accessibility
+
+The package keeps these promises so a call site does not have to. What is left
+is the handful of things only the call site knows — and every one of them is a
+prop that is easy to leave off and impossible to notice afterwards.
+
+## Props the type makes required, and why
+
+These are required in TypeScript because forgetting them ships a control that
+cannot be used without sight. Do not satisfy the type with a placeholder.
+
+| Prop | What it is |
+| --- | --- |
+| `Table.caption` | What the table is a table *of*. Announced before the rows. |
+| `Progress.label` | What is progressing. `aria-valuetext` has nothing else to say. |
+| `Avatar.alt` + `Avatar.fallback` | Who it is, and the initials shown when the image fails. |
+| `FloatingIconButton.label` | There is no text in the button at all. |
+| `Select.label` | The trigger is a button; this is its accessible name. |
+| `Combobox.label` | Same. |
+| `SheetContent.title` | A panel with no name drops a screen reader into an unnamed region. |
+| `AccordionItem.title` | The heading that is also the trigger. |
+| `EmptyState.title` | The state's own name. |
+| `Alert.title` | Optional, but an alert with no title is a coloured paragraph. |
+
+```tsx
+// Incorrect — the type is satisfied and the table is still anonymous
+<Table caption="">
+
+// Incorrect — the caption is not a label for the reader, it is the reader's only orientation
+<Table caption="Table">
+
+// Correct
+<Table caption="Invoices awaiting payment">
+```
+
+Use `showCaption={false}` when the design has no room for a visible caption. The
+caption still reaches assistive tech.
+
+## An icon-only control needs a name
+
+```tsx
+// Incorrect — reads as "button"
+<Button iconOnly><TrashIcon /></Button>
+
+// Correct
+<Button iconOnly aria-label="Delete invoice"><TrashIcon /></Button>
+```
+
+The same applies to any `Button` whose children are only an icon, whether or not
+`iconOnly` is set. `FloatingIconButton` cannot get this wrong — its `label` is
+required.
+
+## Decoration is `aria-hidden`
+
+An icon that repeats the words beside it is noise; an arrow inside a link is
+read out as "north east arrow".
+
+```tsx
+// Incorrect
+<StatusPill tone="success"><CheckIcon /> Available</StatusPill>
+
+// Correct
+<StatusPill tone="success"><CheckIcon aria-hidden="true" /> Available</StatusPill>
+```
+
+## Colour is never the only carrier
+
+Every status tone in the system is doubled by an icon, by the words, or by both.
+Keep that when you compose.
+
+```tsx
+// Incorrect — the only difference between these two rows is a hue
+<TD><span className="text-(--danger)">●</span></TD>
+
+// Correct
+<TD><StatusPill tone="danger">Overdue</StatusPill></TD>
+```
+
+## Do not re-implement a pattern Radix already owns
+
+Focus traps, roving tabindex, typeahead, portal placement and scroll locking are
+where a hand-rolled component quietly becomes unusable with a keyboard. `Dialog`,
+`Sheet`, `Popover`, `DropdownMenu`, `ContextMenu`, `Tabs`, `Accordion`,
+`RadioGroup`, `ToggleGroup`, `Select`, `Slider` and `Tooltip` already wrap it.
+
+```tsx
+// Incorrect
+<div role="dialog" className="fixed inset-0 …" onKeyDown={handleEscape}>
+
+// Correct
+<Dialog><DialogContent title="…">…</DialogContent></Dialog>
+```
+
+## Motion is gated
+
+Anything animated is behind `motion-safe` and carries `data-m22-animated`, so
+the one reduced-motion rule in the package can reach it. If you animate
+something yourself, do both.
+
+```tsx
+// Correct — the package's keyframes are all prefixed `m22-`
+<div data-m22-animated className="motion-safe:animate-[m22-fade-in_200ms_var(--ease-out-expo)]">
+```
+
+`data-motion="still"` on any ancestor stops motion in that subtree.
+
+## The keyboard contract is documented per component
+
+```bash
+npx misoto22-design docs Combobox
+```
+
+prints the key-by-key contract. It is the part that quietly regresses — a
+wrapper that swallows a key looks identical until someone tries it — so check it
+before you wrap one of these in your own handler.

package/skills/misoto22-design/rules/composition.md

@@ -0,0 +1,108 @@
+# Composition
+
+## `className` adjusts layout, never appearance
+
+The caller's `className` is merged last through `cn()`, so it *can* override
+anything. That is what makes the rule necessary rather than enforced.
+
+```tsx
+// Incorrect — re-skins the component, and only in this one place
+<Button className="bg-blue-600 text-white rounded-full px-8 text-lg">
+
+// Correct — the appearance is a variant, the layout is the class
+<Button variant="primary" size="lg" className="w-full">
+```
+
+Legitimate `className`: `w-`, `flex-`, `grid-`, `col-span-`, `m*`, `self-`,
+`order-`. Not legitimate: colour, border, radius, font size, shadow. If the
+appearance you want is not reachable through props and the theme axes, that is a
+gap in the system — say so rather than patching it at one call site.
+
+## Use `cn()` for conditional classes
+
+```tsx
+import { cn } from '@misoto22/design'
+
+// Incorrect — emits both sides of the conflict; stylesheet order picks a winner
+<div className={`p-6 ${dense ? 'p-2' : ''}`}>
+
+// Correct — twMerge resolves by utility group, so p-2 replaces p-6
+<div className={cn('p-6', dense && 'p-2')}>
+```
+
+## Card uses its full set
+
+```tsx
+// Incorrect
+<Card><div className="p-6"><h3 className="font-bold">Usage</h3><p>…</p></div></Card>
+
+// Correct
+<Card variant="outline">
+  <CardHeader><CardTitle>Usage</CardTitle></CardHeader>
+  <CardBody>…</CardBody>
+  <CardFooter><Button>Manage</Button></CardFooter>
+</Card>
+```
+
+`variant`: `outline` (default) · `plate` · `flat`. The part is `CardBody`, not
+`CardContent` — see [naming.md](./naming.md).
+
+## Reach for a component before writing markup
+
+| Instead of | Use |
+| --- | --- |
+| a styled div with an icon and a message | `Alert` |
+| a centred "nothing here yet" block | `EmptyState` |
+| an error page or panel | `ErrorState` |
+| `<hr>` or `border-t` | `Separator` |
+| a custom `animate-pulse` div | `Skeleton` (+ `SkeletonLine` / `SkeletonText` / `SkeletonPage`) |
+| a styled span for a count or state | `Badge`, or `StatusPill` for a live state |
+| a styled span for a keyboard key | `Kbd` |
+| a hand-built breadcrumb trail | `Breadcrumb` |
+| a hand-built page/sidebar frame | `AppShell` |
+| a hand-built numbered process | `Steps` |
+| long-form prose you did not style yourself | `Article` |
+
+## Navigation goes through `asChild`
+
+No component in this package imports a router. A control that navigates takes
+its own element from the call site.
+
+```tsx
+// Incorrect in a Next.js app — a full page load
+<Button href="/settings">Settings</Button>
+
+// Correct
+<Button asChild><Link href="/settings">Settings</Link></Button>
+```
+
+`href` on `Button` renders a plain `<a>`. That is right for an external link and
+wrong for in-app navigation.
+
+## Overlays own their own stacking
+
+`Dialog`, `Sheet`, `Popover`, `DropdownMenu`, `ContextMenu` and `Tooltip` portal
+themselves and read `--z-overlay` / `--z-dropdown`.
+
+```tsx
+// Incorrect
+<DialogContent title="Edit" className="z-50">
+
+// Correct
+<DialogContent title="Edit">
+```
+
+`TooltipProvider` goes once at the app root; `Toaster` too.
+
+## Logical properties, always
+
+`ps-` / `pe-` / `ms-` / `me-` / `start-` / `end-` / `text-start` / `border-s`.
+A physical property breaks RTL, and the package is RTL-correct everywhere else.
+
+## Server and client
+
+The package is compiled per-file, so `'use client'` sits on the components that
+need it. `Button`, `Card`, `Badge`, `Table`, `Alert`, `Separator` and the other
+static primitives stay server-renderable; anything wrapping Radix carries the
+directive itself. Do not add `'use client'` to a page just because it imports
+from here.

package/skills/misoto22-design/rules/forms.md

@@ -0,0 +1,128 @@
+# Forms
+
+`Field` is the form row. It does the ARIA wiring that a hand-rolled label +
+input + error div silently skips, and skipping it is invisible in a browser and
+total for a screen reader.
+
+## A labelled control is a `Field`
+
+```tsx
+// Incorrect — the hint is drawn and never announced, and required is decorative
+<div className="space-y-2">
+  <label htmlFor="email">Email *</label>
+  <Input id="email" />
+  <p className="text-xs text-red-500">Enter a valid email.</p>
+</div>
+
+// Correct
+<Field label="Email" required error="Enter a valid email.">
+  <Input type="email" />
+</Field>
+```
+
+`Field` generates the id, points the label at it, and sets `aria-describedby`,
+`aria-required` and `aria-invalid` on the control.
+
+## Do not repeat what `Field` already sets
+
+Passing `error` sets `aria-invalid` on the control for you. Writing `invalid`
+as well is redundant, and writing a red border class is wrong.
+
+```tsx
+// Redundant
+<Field label="Email" error={message}><Input invalid /></Field>
+
+// Wrong
+<Field label="Email" error={message}><Input className="border-red-500" /></Field>
+
+// Correct
+<Field label="Email" error={message}><Input /></Field>
+```
+
+Reach for `invalid` on the control only when there is no `Field` around it.
+
+## `hint` and `error` are one slot
+
+They are not two stacked messages. `error` replaces `hint` when present: when a
+field is wrong, the thing to read is what is wrong with it.
+
+```tsx
+// Correct — one of the two shows, decided by whether there is an error
+<Field label="Password" hint="At least 12 characters." error={errors.password}>
+  <Input type="password" />
+</Field>
+```
+
+## One control per `Field`
+
+The wiring clones a **single** element child. Two children, or a wrapper div,
+and nothing is wired — the label points at an id that is on nothing.
+
+```tsx
+// Incorrect — the div is the child, so the input gets no id, no describedby
+<Field label="Amount">
+  <div className="flex gap-2"><Input /><Button>Max</Button></div>
+</Field>
+
+// Correct — one Field per control; the row is laid out outside it
+<div className="flex items-end gap-2">
+  <Field label="Amount" className="flex-1"><Input /></Field>
+  <Button>Max</Button>
+</div>
+```
+
+## The controls
+
+| Need | Component | Note |
+| --- | --- | --- |
+| Text, email, number | `Input` | |
+| Multi-line | `Textarea` | |
+| A short list, styled | `Select` | `label` is **required** |
+| A short list, native | `NativeSelect` | Use on mobile-first forms |
+| A long, searchable list | `Combobox` | `options` array, `label` **required** |
+| Boolean, in a form | `Checkbox` | |
+| Boolean, applied immediately | `Switch` | |
+| One of 2–7 visible options | `RadioGroup` + `RadioGroupItem` | |
+| One of 2–7, as a toolbar | `ToggleGroup` + `ToggleGroupItem` | |
+| A number in a range | `Slider` | |
+| A date | `DatePicker` / `DateRangePicker` | |
+
+`Select` and `Combobox` take `label` even inside a `Field` — it is the
+accessible name of the trigger, which is a button, not a labellable control.
+
+## Custom controls read the shared base
+
+Do not re-derive the text-control look. Three exports carry it, and they respond
+to `data-density` and `data-mode` for free.
+
+```tsx
+import { CONTROL_BASE, CONTROL_BORDER, cn, isInvalid } from '@misoto22/design'
+
+function MoneyInput({ invalid, 'aria-invalid': ariaInvalid, className, ...rest }) {
+  const bad = isInvalid(invalid, ariaInvalid)
+  return (
+    <input
+      aria-invalid={bad || undefined}
+      className={cn(CONTROL_BASE, bad ? CONTROL_BORDER.invalid : CONTROL_BORDER.resting, className)}
+      {...rest}
+    />
+  )
+}
+```
+
+`isInvalid()` reads both spellings — `invalid` is the ergonomic prop, and
+`aria-invalid` is what a form library sets. A control that honours only one of
+them loses the error styling for half the ecosystem.
+
+## Layout
+
+`Field` already stacks its own parts. For the gap between fields, use flex with
+`gap`, not margin utilities on the children.
+
+```tsx
+// Correct
+<form className="flex flex-col gap-4">
+  <Field label="Name"><Input /></Field>
+  <Field label="Email"><Input type="email" /></Field>
+</form>
+```

package/skills/misoto22-design/rules/naming.md

@@ -0,0 +1,155 @@
+# Naming — where habit produces an import that does not exist
+
+Most models have read far more shadcn/ui and Radix than they have read this
+package. Those habits produce identifiers that are not exported here, and the
+failure is a TypeScript error at the import line rather than something subtle.
+
+This is the whole divergence list. Everything not on it is spelled the way you
+would guess.
+
+## Compound parts renamed
+
+| Habit | Here |
+| --- | --- |
+| `CardContent` | `CardBody` |
+| `TableHeader` | `THead` |
+| `TableBody` | `TBody` |
+| `TableRow` | `TR` |
+| `TableHead` | `TH` |
+| `TableCell` | `TD` |
+
+```tsx
+// Incorrect
+<Card><CardContent>…</CardContent></Card>
+
+// Correct
+<Card><CardBody>…</CardBody></Card>
+```
+
+## Compounds that are one component with props
+
+These have no sub-parts at all. Reaching for `<XTrigger>` / `<XContent>` fails.
+
+### Dialog and Sheet — the title is a prop
+
+```tsx
+// Incorrect — DialogTitle and DialogHeader are not exported
+<DialogContent>
+  <DialogHeader><DialogTitle>Delete project</DialogTitle></DialogHeader>
+  …
+</DialogContent>
+
+// Correct
+<DialogContent title="Delete project" description="This cannot be undone.">
+  …
+</DialogContent>
+```
+
+`Sheet` is the same shape, and `SheetTitle` does not exist either:
+
+```tsx
+// Incorrect
+<SheetContent><SheetTitle>Filters</SheetTitle>…</SheetContent>
+
+// Correct
+<SheetContent side="end" title="Filters">…</SheetContent>
+```
+
+`SheetContent.title` is required by the type. `DialogContent.title` is optional
+— Radix demands a title either way, so omitting it renders a visually-hidden
+placeholder rather than warning. Pass it anyway: the placeholder keeps the modal
+legal, not useful. When the design calls for no visible heading, pass the title
+and add `hideTitle`, so the accessible name is a real one.
+
+### Tooltip — the content is a prop, and it wraps its trigger
+
+```tsx
+// Incorrect
+<Tooltip>
+  <TooltipTrigger asChild><Button /></TooltipTrigger>
+  <TooltipContent>Copy</TooltipContent>
+</Tooltip>
+
+// Correct — put TooltipProvider once at the app root
+<Tooltip content="Copy"><Button iconOnly aria-label="Copy"><CopyIcon /></Button></Tooltip>
+```
+
+### Alert and EmptyState — tone and title are props
+
+```tsx
+// Incorrect
+<Alert><AlertTitle>Saved</AlertTitle><AlertDescription>…</AlertDescription></Alert>
+
+// Correct
+<Alert tone="success" title="Saved">Your changes are live.</Alert>
+```
+
+`EmptyState` is the same shape: `icon` (a Lucide component, not an element),
+`title`, `description`, `action`.
+
+### Accordion — the item carries its own title
+
+```tsx
+// Incorrect
+<AccordionItem value="a">
+  <AccordionTrigger>Billing</AccordionTrigger>
+  <AccordionContent>…</AccordionContent>
+</AccordionItem>
+
+// Correct
+<AccordionItem value="a" title="Billing">…</AccordionItem>
+```
+
+### Select — one component, `SelectItem` children
+
+```tsx
+// Incorrect
+<Select>
+  <SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger>
+  <SelectContent><SelectItem value="au">Australia</SelectItem></SelectContent>
+</Select>
+
+// Correct — label is required
+<Select label="Region" placeholder="Choose">
+  <SelectItem value="au">Australia</SelectItem>
+</Select>
+```
+
+`SelectRoot` is the raw Radix root, exported for the rare case that needs it.
+Reach for `Select` unless you know why you are not.
+
+### Combobox — an options array, not children
+
+```tsx
+// Correct
+<Combobox
+  label="Assignee"
+  options={[{ value: 'ada', label: 'Ada Lovelace' }]}
+  value={value}
+  onValueChange={setValue}
+/>
+```
+
+## Compounds that ARE compounds
+
+Spelled as expected, no surprises: `Popover`, `DropdownMenu`, `ContextMenu`,
+`Command`, `Tabs`, `Collapsible`, `RadioGroup`, `ToggleGroup`, `Skeleton`.
+
+## Imports that come from here, not from upstream
+
+| Habit | Here |
+| --- | --- |
+| `import { toast } from 'sonner'` | `import { toast } from '@misoto22/design'` |
+| `import { cn } from '@/lib/utils'` | `import { cn } from '@misoto22/design'` |
+
+`<Toaster />` goes once at the app root, and it is exported from here too.
+
+## When in doubt
+
+```bash
+npx misoto22-design docs <Component>
+```
+
+That prints the component's real exports, every prop with its type and default,
+and its keyboard contract, read out of the installed source. It is cheaper than
+a wrong import and a retry.

package/skills/misoto22-design/rules/tokens.md

@@ -0,0 +1,131 @@
+# Colour, theming and spacing
+
+The system is monochrome by construction: paper ground, near-black mark, and
+status is the only chroma. A raw colour class is not a style choice here, it is
+a hole in the theme — it survives the light/dark swap unchanged and it ignores
+every surface axis.
+
+## Never write a raw colour
+
+```tsx
+// Incorrect
+<div className="bg-white text-gray-500 border-neutral-200">
+<div className="bg-neutral-900 dark:bg-white">
+<div style={{ color: '#101010' }}>
+
+// Correct
+<div className="bg-(--background) text-(--foreground-muted) border-(--border-color)">
+```
+
+The semantic layer is the one to read. It is shipped as its own entry point
+(`@misoto22/design/semantic.css`) and it is what the components themselves use.
+
+| Role | Token |
+| --- | --- |
+| Page ground | `--background` |
+| One step off the ground | `--background-elevated` |
+| Card ground | `--card-background` |
+| Body text | `--foreground` |
+| Quieter text | `--foreground-muted` |
+| Quietest text that still clears AA | `--secondary-text` |
+| Edge | `--border-color` |
+| Hairline | `--border-subtle` |
+| A chosen state — primary button, checked box, active tab | `--accent` |
+| Text on an accent fill | `--accent-foreground` |
+| Text on an accent wash | `--accent-on-muted` |
+| Status | `--success` `--warning` `--danger` `--info`, each with a `-wash` |
+| Text over a photograph | `--on-dark` |
+
+Prefer these over the primitive layer (`--paper`, `--ink`, `--rule`, `--stone`).
+Primitives are values; semantics are roles, and a role can be re-pointed without
+a component changing. `--card-background` is already an alias for a surface that
+was retired — that is the layer doing its job.
+
+## Never write a `dark:` variant
+
+```tsx
+// Incorrect — freezes one side of the swap
+<div className="bg-white dark:bg-neutral-900">
+
+// Correct — the token already resolves in both
+<div className="bg-(--background)">
+```
+
+Dark mode is a value swap on the primitives behind `[data-mode="dark"]`. Any
+semantic token re-resolves on its own. A `dark:` class is a second, competing
+theme that will disagree with the first the moment a surface axis is set.
+
+## Theme with the seven axes
+
+Each is an attribute, each is independent, and each works on **any element** —
+not just `:root`. An unset axis is the default.
+
+| Attribute | Values | Unset means |
+| --- | --- | --- |
+| `data-mode` | `light` `dark` | follows the app |
+| `data-surface` | `warm` `cool` `glass` | paper |
+| `data-radius` | `sharp` `round` | the default ladder |
+| `data-rules` | `quiet` `firm` | hairline |
+| `data-type` | `grotesk` `bookish` | editorial |
+| `data-motion` | `still` `snappy` | calm |
+| `data-density` | `compact` | comfortable |
+
+```tsx
+// A warm, square, dense panel inside an otherwise default page.
+<section data-surface="warm" data-radius="sharp" data-density="compact">…</section>
+```
+
+There is **no `data-accent` attribute.** `--accent` is a single CSS custom
+property; re-skin the system by re-pointing it in your own stylesheet, not by
+setting an attribute.
+
+```css
+/* Correct way to re-accent */
+:root { --accent: var(--ok); --accent-hover: var(--ok-ink); }
+```
+
+## Radius, duration and control size come from tokens
+
+```tsx
+// Incorrect
+<div className="rounded-lg duration-150 min-h-11">
+
+// Correct
+<div className="rounded-(--radius) duration-(--duration-fast) min-h-(--control-h-md)">
+```
+
+`--control-h-md` is 44px comfortable / 36px compact. Hard-coding `min-h-11`
+means the control never responds to `data-density`, and `min-height` is a floor,
+so it also never shrinks.
+
+Durations: `--duration-fast` `--duration-base` `--duration-slow`. Easing:
+`--ease-out-expo`.
+
+## No blurred shadow
+
+`--shadow`, `--shadow-sm` and `--shadow-lg` all resolve to `none` on purpose.
+The system has no elevation ramp. Depth is a hairline, a change of ground, or
+`--lift` — a hard ink offset with no blur.
+
+```tsx
+// Incorrect
+<div className="shadow-lg">
+
+// Correct
+<div className="shadow-(--lift)">
+```
+
+## Logical properties, always
+
+The package is RTL-correct and a physical property breaks it.
+
+```tsx
+// Incorrect
+<div className="pl-4 ml-2 text-left border-l">
+
+// Correct
+<div className="ps-4 ms-2 text-start border-s">
+```
+
+Tailwind has no logical `translate`, so anything sliding along the inline axis
+needs an explicit `rtl:` counterpart.