# Quartz

Black and white chassis with five muted kind hues and warm trouble colors, for AI support products and agent consoles.

## Setup
Once, in the root layout: put the "quartz" class on `<body>` or the root element of the UI, with `QuartzPortalProvider` inside it. Quartz's styles and tokens apply only inside that class.
Menus, dialogs, popovers and toasts render at the end of the body; QuartzPortalProvider keeps them inside the scope, and without it they lose every token. `import {QuartzPortalProvider} from '@/lib/quartz/portal'`
`<body className="quartz"><QuartzPortalProvider>{children}</QuartzPortalProvider></body>`

## Steps
1. For a whole screen, start from a block under Blocks when one fits: install it, then swap its sample data and copy for the real ones.
2. Pick the components the screen needs from the index below. Fetch each one's page before using it: it has the props, variants and that component's rules.
3. Build only from those components and the tokens under Tokens, inside an element with the "quartz" class. Import each from the path in the index; support pieces are under Imports. Dark mode: put data-theme="dark" or the class dark on the quartz element or any ancestor, such as <html>. The theme does not follow the system setting (prefers-color-scheme) on its own.
4. Frame the screen with the Page shell. If a component is missing, build the stand-in under Coverage gaps; if none is listed, compose it from existing components and tokens and say what you built. Never invent a token.
5. Ask the person when the screen needs a credential, an environment, the object of a destructive action or an approval policy you were not given; never invent a key, an endpoint or which tools need approval. Decide layout, copy and components from these rules and say what you chose.
6. Porting an existing screen: swap one piece at a time for its component, keep the behavior and copy, and delete the old styles once nothing uses them. For a whole app, run migrate-design-system when it is installed.
7. Lint: install it once with `npx shadcn@latest add https://design.how/r/quartz/lint.json`, then run `npx eslint -c quartz.eslint.config.mjs .`. Each message names the fix.
8. Review before you finish: run the lint and fix every error, then render the screen at 390 and 1280 wide, check it against the global rules and the anti-slop list, fix the worst defect, and check again. Done when no MUST or NEVER is broken and no raw color, size or font is left. Run ui-review when it is installed.

## Priority order
When rules conflict, the earlier item wins.
1. Accessibility and keyboard behavior
2. Tokens, never raw values
3. Existing components, never rebuilt
4. Layout and spacing scale
5. Polish: motion, radius, details

## Global rules
1. quartz-components-first MUST Use a component from this system before writing custom markup. Because hand-built markup skips the component's focus ring, keyboard handling and states, which people notice one at a time.
   - Correct: `<Button onClick={open}>Open run</Button>`
   - Wrong: `<div onClick={open} className="cursor-pointer">Open run</div>`
2. quartz-scope MUST Put className="quartz" on `<body>`, once, in the root layout, with QuartzPortalProvider inside it. Because the class carries every token and the font, and the provider gives menus, dialogs and toasts a home beside the page so a modal can make the page behind inert.
   - Correct: `<body className="quartz"><QuartzPortalProvider>{children}</QuartzPortalProvider></body>`
   - Wrong: `<div className="quartz"><QuartzPortalProvider>{children}</QuartzPortalProvider></div>`
3. quartz-tokens-only MUST Reference tokens by role; never hex, rgb or arbitrary px. Because a raw value keeps its light-theme color in the dark theme and drifts off the spacing scale.
   - Correct: `<div className="bg-surface p-4">`
   - Wrong: `<div className="bg-[#f4f4f5] p-[13px]">`
4. quartz-kind-is-a-word MUST Name a kind with <Badge kind/> or data-kind; hue never fills a region. Because the word reads in grayscale and aloud, and a filled region makes everything inside look like that kind.
   - Correct: `<Badge kind="agent"/>`
   - Wrong: `<Card className="bg-accent-field">Agent</Card>`
5. quartz-warm-is-trouble NEVER Use amber or red for anything but warn and fail. Because an operator scanning for trouble stops on every warm mark, so a warm Beta tag reads as a failing run.
   - Correct: `<Badge>Beta</Badge>`
   - Wrong: `<Badge className="bg-amber-200">Beta</Badge>`
6. quartz-prop-names SHOULD Name a prop by the question it answers: status for warn and fail, orientation for the direction a row or column runs, layout for which arrangement of the same parts, placement for where it sits on the page; variant only for a Button and a menu item's intent. Because one word for one question lets a person guess the prop on a component they have not used, and tone, kind or variant for a state sends them to the docs.
7. quartz-fields-not-lines SHOULD Separate containers with 

…