division-ds 0.1.2 → 0.2.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Division DS: instructions for coding agents
 
-A React 19 + Tailwind 4 + Radix design system: 67 components, tokens in three layers, light and
+A React 19 + Tailwind 4 + Radix design system: 68 components, tokens in three layers, light and
 dark themes, WCAG 2.2 AA. This file is the entry point. It is short on purpose; everything it
 points to is generated from the code, so it is current.
 
@@ -11,6 +11,7 @@ points to is generated from the code, so it is current.
 | The list of components, one line each | `public/llms.txt` |
 | One component: props, examples as code, keyboard, do and don't | `public/docs/components/<slug>.md` |
 | Every component's props in one compact file | `public/llms-components.txt` |
+| The whole system in one short file (for a tool that takes one design file) | `public/DESIGN.md` |
 | Which token to use for what | `public/llms-tokens.txt` |
 | Shared helpers: form errors, money, links, theme, streamed text | `public/docs/helpers.md` |
 | The same as data | `public/manifest/components.json`, `public/manifest/tokens.json` |
@@ -42,10 +43,17 @@ npx division-ds check <files or dirs>          (from npm; Node 22 or newer)
 node <path-to-division-ds>/scripts/division-ds.mjs check <files or dirs>   (the same, from a clone)
 ```
 
-It runs the colour and button-spacing gates and checks every Division DS element's props against
+It runs the colour, button-spacing and AI copy gates and checks every Division DS element's props against
 `public/manifest/components.json`: an unknown prop, or a value that is not in the prop's union.
 Exit 1 means a finding; each one says what to write instead. `division-ds rules --target <dir>`
 installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rules.
+`division-ds skill --target <dir>` installs the skill into `.agents/skills/` (Codex, Cursor) and
+`.claude/skills/` (Claude Code).
+
+An agent that supports MCP can have the docs and the same checks as tools instead:
+`claude mcp add division-ds -- npx -y division-ds@0.2.1 mcp` (`list_components`, `get_component`,
+`search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
+`get_review_checklist`).
 
 <!-- rules:start -->
 ## Rules
@@ -108,7 +116,9 @@ The shell paints the page background (`surface.base`) and supplies the gutter; a
 own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
 exception: it paints `surface.base` on itself, so its field colours never depend on what is
 behind it. In a project that uses the components, your own root does this
-(step 4 of `install.md`).
+(step 4 of `install.md`). Toggle it with `setTheme()` from `src/lib/theme.ts`.
+
+**App navigation.** A few views: `Navbar` (`current: true` on the open one). Many: `Sidebar`.
 
 **Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
 default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is
@@ -143,6 +153,9 @@ bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`,
 renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the state (signature in
 `public/docs/helpers.md`).
 
+A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
+page). A date is `<Input type="date">` in a `FormField`.
+
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is
 `type="button"` unless you say `type="submit"`. A busy button takes `loading`, not `disabled`.
@@ -175,6 +188,13 @@ element arriving, `anim-draw-on` for a hairline) and the motion tokens (`--durat
 hover, `--duration-base` by default, `--duration-slow` for a larger change, `--ease-snap`).
 Anything you animate yourself stops under `prefers-reduced-motion` (`motion-reduce:` in
 Tailwind), and nothing moves on its own: no autoplay.
+
+<!-- topic: ai -->
+
+**Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
+"answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
+messages say "I". Response feedback: `ResponseFeedback` in `actions`.
+A value the assistant filled is `aiValue` on that `Input` or `Textarea` only; leaving it accepts it.
 <!-- rules:end -->
 
 ## Changing the system itself

package/README.md

@@ -16,4 +16,15 @@ npx division-ds rules     # writes the Division DS rules into AGENTS.md / CLAUDE
 npx division-ds help
 ```
 
+## For agents: the MCP server
+
+```bash
+claude mcp add division-ds -- npx -y division-ds mcp
+```
+
+Any MCP client works the same way: the command is `npx -y division-ds mcp`, on stdio. It gives the
+agent eight tools: `list_components`, `get_component`, `search`, `get_tokens`,
+`validate_code` (the checks above, on code the agent just wrote), `check_contrast` (WCAG 2.2 AA,
+both themes), `get_add_command` and `get_review_checklist`.
+
 The components, the docs and the agent skill: https://github.com/Victor-Ilioiu/division-ds

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "division-ds",
-  "version": "0.1.2",
-  "description": "Checks a project that uses Division DS components: raw colours, invented tokens, touching buttons, unknown props.",
+  "version": "0.2.1",
+  "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",
   "homepage": "https://victor-ilioiu.vercel.app/systems/division-ds/",

package/public/docs/components/accordion.md

@@ -0,0 +1,207 @@
+# Accordion
+
+> Sections that open and close in place, each under its own heading. You can allow one open at a time or several, and draw them as plain rows split by thin lines or as a panel per section.
+
+- **Best for:** Sections people scan by heading and open one or two of: frequently asked questions (FAQ), grouped settings, long specifications.
+- **Not for:** Steps in a sequence: use Stepper. Equal views of the same thing: use Tabs.
+- Molecule. Source: `src/components/molecules/accordion/Accordion.tsx`
+- Rendered docs page: `/components/accordion`
+
+## Import
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'src/components/molecules/accordion/Accordion'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `type` | `'single' \| 'multiple'` |  | Required on the root. single: opening one section closes the other. multiple: any number can be open. |
+| `collapsible` | `boolean` | `false` | single mode only. Lets the open section be closed again by its own trigger. You'll want it almost always. |
+| `variant` | `'plain' \| 'boxed'` | `'plain'` | plain: thin separator lines, for a long run of questions. boxed: a panel per section, for a few sections that each stand alone. |
+| `value (Root)` | `string \| string[]` |  | The open section when the page controls it: a string in single mode, an array in multiple mode. |
+| `defaultValue` | `string \| string[]` |  | The section or sections open at first, when the accordion keeps track itself (uncontrolled). Set on the root. |
+| `onValueChange` | `(value: string \| string[]) => void` |  | Called when a section opens or closes (on the root). The argument has the same shape as type. |
+| `value (Item)` | `string` |  | Required. The section’s own value. |
+| `disabled (Item)` | `boolean` | `false` | The section can't be opened or closed. |
+| `level (Trigger)` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | The level of the heading the trigger sits in. Pick one below the heading the accordion appears under. |
+| `forceMount (Content)` | `true` |  | Keeps a closed panel in the page's code (the DOM, the browser's live model of the page), so the browser's find-in-page search can reach its content. It then skips the closing animation. |
+| `className` | `string` |  | Merged with each part’s classes. On AccordionContent it goes on the inner padded box, not the animated clipping box around it. |
+| `ref` | `Ref<HTMLElement>` |  | Passed through to the DOM element. Every part has one; the trigger’s is the button. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AccordionVariant = 'plain' | 'boxed'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Frequently asked questions (FAQ): plain style, one answer open at a time, and the open one can be closed again
+
+```tsx
+<div className="w-full max-w-lg">
+  <Accordion type="single" collapsible>
+    <AccordionItem value="shipping">
+      <AccordionTrigger>How long does shipping take?</AccordionTrigger>
+      <AccordionContent>
+        Two to four working days inside the EU. Every parcel leaves the depot with a tracking
+        number, sent to you by email the same day.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="returns">
+      <AccordionTrigger>Can I return a replica?</AccordionTrigger>
+      <AccordionContent>
+        Within 30 days, unfired and in its original box. Open a return from your order page and
+        print the label.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="age">
+      <AccordionTrigger>Do I need to prove my age?</AccordionTrigger>
+      <AccordionContent>
+        Yes, once. We check an ID document at the first order of a replica; accessories need no
+        check.
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="custom" disabled>
+      <AccordionTrigger>Custom builds (paused)</AccordionTrigger>
+      <AccordionContent>The workshop takes no new builds this season.</AccordionContent>
+    </AccordionItem>
+  </Accordion>
+</div>
+```
+
+### Settings sections: boxed style, several open at once, and each section header is a level-2 heading (h2)
+
+```tsx
+function SettingRow({ id, label, defaultChecked }: { id: string; label: string; defaultChecked?: boolean }) {
+  return (
+    <div className="flex items-center justify-between gap-4 py-2">
+      <label htmlFor={id} className="text-sm text-[var(--color-text-primary)]">
+        {label}
+      </label>
+      <Switch id={id} defaultChecked={defaultChecked} />
+    </div>
+  )
+}
+
+<div className="w-full max-w-lg">
+  <Accordion type="multiple" variant="boxed" defaultValue={['notifications']}>
+    <AccordionItem value="notifications">
+      <AccordionTrigger level={2}>Notifications</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-shipping" label="Shipping updates" defaultChecked />
+        <SettingRow id="acc-set-restock" label="Restock alerts" />
+        <SettingRow id="acc-set-news" label="Monthly newsletter" />
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="privacy">
+      <AccordionTrigger level={2}>Privacy</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-profile" label="Show my squad profile" defaultChecked />
+        <SettingRow id="acc-set-history" label="Keep order history" defaultChecked />
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="display">
+      <AccordionTrigger level={2}>Display</AccordionTrigger>
+      <AccordionContent>
+        <SettingRow id="acc-set-motion" label="Reduce motion" />
+      </AccordionContent>
+    </AccordionItem>
+  </Accordion>
+</div>
+```
+
+### Controlled: the page keeps track of which sections are open
+
+```tsx
+function ControlledExample() {
+  const [open, setOpen] = useState<string[]>(['battery'])
+  return (
+    <div className="w-full max-w-lg">
+      <p className="mb-3 font-mono text-xs uppercase tracking-[0.18em] text-[var(--color-text-secondary)]">
+        Open: {open.length ? open.join(', ') : 'none'}
+      </p>
+      <Accordion type="multiple" value={open} onValueChange={setOpen}>
+        <AccordionItem value="battery">
+          <AccordionTrigger>Battery</AccordionTrigger>
+          <AccordionContent>11.1V LiPo, 1450mAh, with a deans connector.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="hop-up">
+          <AccordionTrigger>Hop-up</AccordionTrigger>
+          <AccordionContent>Rotary adjustment, 60 degree bucking.</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  )
+}
+
+<ControlledExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves between triggers, and into an open section’s content. |
+| `Enter` `Space` | Opens or closes the focused section. |
+| `↓` `↑` | Goes to the next or previous trigger, wrapping round at the ends and skipping disabled ones. |
+| `Home` `End` | Goes to the first or last trigger. |
+
+## Do
+
+- Use it for content people scan by its headings and open one or two of: an FAQ, a group of settings, long specifications.
+- Write each trigger as the question or the section name, so the closed list reads like a table of contents.
+- Set collapsible in single mode.
+- Use boxed for a few sections that each hold controls, and plain for a long list of text answers.
+
+## Don't
+
+- Don't hide the one thing everyone needs inside a closed section. Show it.
+- Don't use it for steps in a sequence. That's Stepper.
+- Don't use it to switch between equal views of the same thing. That's Tabs.
+- Don't nest an accordion inside another accordion's content.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Accordion type="single">
+```
+
+Right:
+
+```tsx
+<Accordion type="single" collapsible>
+```
+
+Without collapsible, a single-mode accordion can never be fully closed again once a section is open. That surprises people.
+
+Wrong:
+
+```tsx
+<AccordionTrigger>Shipping</AccordionTrigger> // under an h3 section title
+```
+
+Right:
+
+```tsx
+<AccordionTrigger level={4}>Shipping</AccordionTrigger>
+```
+
+Every trigger (the clickable section header) sits inside a heading, h3 (a level-3 heading) by default. Set level so the triggers nest one level below the heading they appear under.
+
+## Anatomy
+
+- **Accordion**: The root. It holds which sections are open and the variant, and every part below reads both.
+- **AccordionItem**: One section. plain: a thin line under it. boxed: its own raised panel with the cut corner. The panel is drawn on a backing layer marked aria-hidden (hidden from screen readers), so the item itself is never clipped.
+- **AccordionTrigger**: A button inside a heading of the level you choose. It uses the display typeface, has a chevron that turns half a revolution when the section is open, and is underlined on hover.
+- **AccordionContent**: A region labelled by its trigger, in secondary text. It grows open over the base duration and shrinks shut faster (M7). When someone has asked their device for reduced motion, it snaps open and shut instead.

package/public/docs/components/ai-label.md

@@ -0,0 +1,90 @@
+# AiLabel
+
+> Marks content as made by AI, and on request says why. Given an explanation, the mark is a button that opens a short note right under it, with an optional list of sources. It is a disclosure (a button that shows and hides a region), not a tooltip or a popover: a tooltip can't hold links and never shows on a touch screen, and the system has no popover.
+
+- **Best for:** Marking a block of text, a value or a field that an AI wrote, so the person knows to check it.
+- **Not for:** A status or a category: use Badge. A field the AI filled: give the field aiValue, which marks it itself.
+- Atom. Source: `src/components/atoms/ai-label/AiLabel.tsx`
+- Rendered docs page: `/components/ai-label`
+
+## Import
+
+```tsx
+import { AiLabel } from 'src/components/atoms/ai-label/AiLabel'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `'Generated by AI'` | The mark's words, and the button's name. Say what the AI made: 'AI summary', 'AI draft'. |
+| `explanation` | `ReactNode` |  | Why this is AI content and what to do about it, in a sentence or two: what it was made from, and that it needs checking. Without it the mark is static text and nothing opens. |
+| `sources` | `AiLabelSource[]` |  | { label, href } for each thing the content was made from. Listed under the explanation; ignored without one. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | How each source link is drawn. Pass your router's link component for sources inside the app. |
+| `className` | `string` |  | Merged with the root's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root div. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` |  | Every native attribute, onto the root div. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type AiLabelSource = { label: string; href: string }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Static mark
+
+```tsx
+<AiLabel />
+```
+
+### With an explanation and sources
+
+```tsx
+<div className="flex flex-col gap-2 max-w-md">
+  <AiLabel
+    label="AI summary"
+    explanation="Summarised from the three most recent reviews of this replica. It can miss details or get them wrong: verify before you rely on it."
+    sources={[
+      { label: 'Review by Ilse Varga', href: '#review-1' },
+      { label: 'Review by Tomas Brandt', href: '#review-2' },
+    ]}
+  />
+  <p className="text-sm text-[var(--color-text-primary)]">
+    Reviewers find the gearbox quiet and the hop-up easy to tune; two mention a loose stock.
+  </p>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the mark when it has an explanation, then into any source links once open. |
+| `Enter` `Space` | Opens or closes the explanation. Focus stays on the button. |
+
+## Do
+
+- Put it right above or beside the AI content it marks, not in a page header far away.
+- Say in the explanation what the AI used and that the person should check it, the way GitLab's 'Verify before use' does.
+- Name the sources when there are any. Showing where it came from is how a reader decides whether to trust it.
+
+## Don't
+
+- Don't put it inside a <label>. A button inside a label is read into the field's name; put it beside the label.
+- Don't mark everything. A label on every line is a label on nothing.
+- Don't rely on the colour. The words say AI; ai.text only helps you find them.
+
+## Anatomy
+
+- **Mark**: A sparkle and the label in uppercase mono, in ai.text. Static text when there is no explanation.
+- **Disclosure button**: With an explanation, the mark is a button with aria-expanded and a chevron that turns when open. Its name is the label.
+- **Explanation**: A region right under the button, edged in ai.border, in text.secondary. Hidden until asked for, then next in the reading order.
+- **Sources**: Optional. A list of links under the explanation, drawn through renderLink.