@etus/seven-skill 0.1.0-beta.1

package/.claude/skills/seven/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: seven
+description: Use when generating or auditing UI for the Seven Design System — ETUS Digital's React 19 + Tailwind v4 + @etus/tokens system. Covers component generation, variant selection, token consumption, typography (Inter only), color (OKLCH mint and lime brand, fuchsia chart-only), spatial design (two radius scales), motion (200ms tactile press), accessibility (WCAG 2.1 AA), pt-BR voice (sentence case, no trailing periods, imperative leads), and anti-pattern audits. Routes sub-commands shape, audit, polish, clarify. Not for backend or non-UI tasks.
+version: 0.1.0-beta.1
+argument-hint: "[command] [target]"
+user-invocable: true
+allowed-tools:
+  - Bash(npx seven *)
+license: Apache-2.0
+---
+
+Designs and ships production interfaces with the Seven Design System. Seven is what ETUS Digital uses internally; this skill makes the AI fluent in its tokens, components, voice, and refusals.
+
+## Setup
+
+Before any design work or file edits:
+
+1. Load context (`PRODUCT.md`, `DESIGN.md`) at the project root via the loader script.
+2. Identify the register and apply the matching register reference: [reference/product.md](reference/product.md) (default) or [reference/brand.md](reference/brand.md).
+3. **If the user invoked a sub-command (`shape`, `audit`, `polish`, `clarify`), load its reference file too.** Non-negotiable. Audit without `audit.md` loaded means you skip the five-dimension scan the user expects.
+
+Skipping these produces generic output that ignores Seven.
+
+### 1. Context gathering
+
+Two files, case-insensitive, looked up at the project root by default. Override with `SEVEN_CONTEXT_DIR=path/to/dir`.
+
+- **`PRODUCT.md`**: required. Register, users, brand personality, anti-references, design principles.
+- **`DESIGN.md`**: optional but strongly recommended. Colors, typography, layout, elevation, shape, components.
+
+Load both in one call:
+
+```bash
+node .claude/skills/seven/scripts/load-context.mjs
+```
+
+Consume the full JSON output. Do not pipe through `head`, `tail`, `grep`, or `jq`.
+
+If `PRODUCT.md` is missing, empty, or placeholder ([TODO] markers, under 200 chars), surface the gap to the user and use the AskUserQuestion tool before continuing. Seven's product register is the difference between Seven-on-brand output and generic shadcn.
+
+If `DESIGN.md` is missing, nudge once per session and proceed — `packages/tokens/dist/tokens.css` carries the numeric truth.
+
+### 2. Register
+
+Every design task belongs to one of two registers:
+
+- **`product`** (default for Seven): app UI, admin, dashboards, settings, internal tools. Earned familiarity is the bar. Surfaces look like Linear, Figma, Notion, Raycast in their best moments, never like generic shadcn defaults.
+- **`brand`**: marketing pages, campaign surfaces, long-form content. Distinctiveness is the bar. Phase 2 brand layer fleshes this out per ETUS sub-brand.
+
+First match wins: (1) cue in the task ("dashboard" vs "landing page"), (2) surface in focus, (3) `Register` field in `PRODUCT.md`.
+
+Load the matching reference. Shared design laws below apply to both.
+
+## Source-of-truth ladder
+
+When values disagree, walk the ladder top to bottom:
+
+```
+Figma (Core Components, Seven file)  >  packages/tokens/dist/tokens.css  >  DESIGN.md  >  docs/cd/Seven Design System  >  any other doc
+```
+
+For numeric values (sizes, radii, colors), Figma via the Figma MCP is the source. The HTML extraction skill at `docs/cd/Seven Design System/` can drift; trust Figma, not the extraction.
+
+## Shared design laws
+
+Apply to every Seven task, both registers. Claude is capable of decisive design choices. Pick a direction, name the tradeoff, ship the variant. No hedging.
+
+### Color
+
+- OKLCH only. Read tokens from `@etus/tokens`, never invent.
+- Mint (`var(--brand-primary-500)`) and lime (`var(--brand-secondary-500)`) are the only brand colors. Fuchsia is reserved for charts, never UI chrome.
+- Pure `#000` and `#fff` are banned. Use the tinted neutrals from the OKLCH ramp.
+- Tailwind v4 arbitrary values referencing color tokens require the `color:` hint:
+  ```tsx
+  bg-[color:var(--primary)]           // CORRECT
+  bg-[var(--primary)]                 // WRONG — Lightning CSS drops it silently
+  ```
+  See [reference/color-and-contrast.md](reference/color-and-contrast.md) for the full type-hint rule set.
+
+### Typography
+
+- Inter is the only sans face — UI, body, headings, display.
+- JetBrains Mono is the only mono face.
+- Space Grotesk and Geist appear in legacy Figma exploration. They never shipped. Substitute Inter at the same size and flag the swap.
+- Sentence case across every chrome surface. Acronyms (KPI, OTP, OIDC) stay uppercase.
+- No trailing periods on buttons, labels, or captions.
+
+See [reference/typography.md](reference/typography.md) for the full rule set.
+
+### Shape and elevation
+
+- Two radius scales, never mixed: component (`sm 4 / md 8 / lg 12`) for buttons, inputs, badges; surface (`xl 16 / 2xl 20 / 3xl 24 / 4xl 32`) for cards, dialogs, sheets.
+- Pill radius (`9999`) for badges, tags, avatar triggers, and status indicators only. Never on buttons.
+- Borders carry hierarchy. Shadows are reserved for overlays.
+
+See [reference/spatial-design.md](reference/spatial-design.md).
+
+### Motion
+
+- Default duration 200 ms (`var(--duration-normal)`), easing `var(--ease-default)`.
+- No bounce, no spring, no elastic in chrome.
+- The tactile micro-press is system-wide: every clickable affordance gets `hover:translate-y-px` plus `active:translate-y-0.5` plus an inset shadow, not just `<Button>`.
+
+See [reference/motion-design.md](reference/motion-design.md).
+
+### Voice and locale
+
+- Pt-BR for product chrome. Imperative leads (`Procurar`, `Exportar`, `Adicionar conta`).
+- No European Portuguese vocabulary in pt-BR surfaces.
+- English for code identifiers, file names, architecture notes, and developer-facing docs.
+
+See [reference/ux-writing.md](reference/ux-writing.md).
+
+### Iconography
+
+- Lucide only. 2 px stroke, round caps, `currentColor`.
+- No emoji in chrome. No Unicode dingbats.
+- If a glyph is missing in Lucide, draw a custom SVG matching the 2 px stroke and round-caps spec.
+
+## Component generation checklist
+
+Before writing or editing a Seven component:
+
+1. **Does it exist in `@etus/ui`?** Import it. Do not reimplement.
+2. **Does the variant exist?** Check the component's `*.variants.ts` (CVA). If the variant you need is not there, stop. Seven follows the rule: no variants in code that do not exist in Figma. Surface the gap to the user instead of inventing.
+3. **Do the tokens exist?** Read `packages/tokens/dist/tokens.css` and use the CSS variable directly. Do not invent tokens.
+4. **Type hints on arbitrary values.** `[color:var(--...)]` for color, `[length:var(--...)]` for font-size and line-height. No `hsl(var(--...))`.
+5. **Tactile press plus 4 px focus ring** on every clickable affordance.
+6. **Sentence case, pt-BR copy, no trailing periods.**
+
+## When the user asks for something off-system
+
+Surface the conflict. Do not silently comply.
+
+- "Make the button purple" — "Seven brand is mint and lime. Fuchsia exists but is chart-only. I can use `var(--brand-secondary)` (lime), or flag this as a deliberate one-off and document it."
+- "Use Space Grotesk for the H1" — "Inter is the only sans face in Seven. Space Grotesk in the Figma library is legacy exploration. I will use Inter at the same size; flag if you wanted a one-off override."
+- "Add a hover bounce" — "Seven motion is `var(--ease-default)` (decelerated, no bounce). The 200 ms hover is the standard. Surface this as a deliberate exception?"
+
+## Commands
+
+| Command                           | Category | Reference                                    | Description                                                                             |
+| --------------------------------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `/seven shape`   | Plan     | [reference/shape.md](reference/shape.md)     | Plan UX shape before code. Resolve scope, register, and variants up front.              |
+| `/seven audit`   | Verify   | [reference/audit.md](reference/audit.md)     | Five-dimension scan: a11y, performance, theming, responsive, anti-patterns.             |
+| `/seven polish`  | Refine   | [reference/polish.md](reference/polish.md)   | Final pass. Align drift to Seven tokens and conventions; name root cause.               |
+| `/seven clarify` | UX copy  | [reference/clarify.md](reference/clarify.md) | UX copy in pt-BR: imperative leads, sentence case, no trailing periods, plain language. |
+
+Phase 2 adds `craft`, `harden`, `layout`, `typeset`.
+
+## Related skills
+
+- **`frontend-dev-guidelines`** — React 19, Tailwind v4, TanStack patterns. Seven is the _what_; `frontend-dev-guidelines` is the _how to build it_.
+- **`figma-sync`** — pulls Figma changes into `packages/tokens` and `packages/ui`. Use it when you need to know what changed in Figma, not what Seven looks like.
+- **`component-audit`** — auditing existing components against Figma parity, with the canonical Button.md template as the gold standard.
+
+## See also
+
+- `PRODUCT.md` at repo root for register, users, anti-references.
+- `DESIGN.md` at repo root for the Google Labs visual identity spec.
+- `packages/tokens/dist/tokens.css` for the runtime CSS variables.
+- `packages/ui/src/components/` for component source.
+

package/.claude/skills/seven/reference/audit.md

@@ -0,0 +1,120 @@
+# Audit
+
+Run systematic technical quality checks on a Seven surface or component and generate a report. The audit documents issues; it does not fix them. Hand findings to `polish` or to direct implementation.
+
+## Scope
+
+Code-level audit, not design critique. Check what is measurable and verifiable against `@etus/ui`, `@etus/tokens`, and Seven's documented rules.
+
+## Five-dimension diagnostic scan
+
+Score each dimension 0-4 using the criteria below. The detector ships rule IDs you can cite directly.
+
+### 1. Accessibility (a11y)
+
+Check for:
+
+- Text contrast ratios below 4.5:1 (or 3:1 for large text). Verify against the OKLCH math from `@etus/tokens`, not eyeballed.
+- Missing ARIA roles, labels, or states on interactive elements built from non-semantic primitives.
+- Keyboard traps, missing focus indicators, illogical tab order.
+- Improper heading hierarchy, missing landmarks, `<div onClick>` instead of `<button>`.
+- Image and icon-only buttons without accessible names.
+- Forms with inputs missing labels, error messages missing `aria-describedby`, required state not announced.
+- `prefers-reduced-motion` not honored.
+
+Scoring: 0 = fails WCAG A, 1 = major gaps, 2 = partial, 3 = WCAG AA mostly met, 4 = AA fully met and approaching AAA.
+
+### 2. Performance
+
+Check for:
+
+- Layout thrashing in loops.
+- Animation on CSS layout properties (`width`, `height`, `top`, `left`). Transform and opacity only.
+- Unbounded blur, filter, shadow effects that visibly drop frames.
+- Images without `loading="lazy"`, unoptimized assets, missing dimensions.
+- Unnecessary re-renders, missing `useMemo` or `React.memo` where measurement shows benefit (do not memoize speculatively).
+- Heavy imports pulled in eagerly when a dynamic import would do.
+
+Scoring: 0 = severe issues, 1 = major problems, 2 = partial optimization, 3 = mostly optimized, 4 = lean and fast.
+
+### 3. Theming
+
+Check for:
+
+- Hardcoded color literals in runtime code. Hex inside `packages/tokens/sources/` is fine; anywhere else is drift. Detector rule: `hardcoded-color-not-token`.
+- Pure `#000` and `#fff`. Detector rule: `pure-black-or-white`.
+- Tailwind v4 arbitrary values referencing color tokens without the `color:` hint. Detector rule: `missing-color-type-hint`.
+- Font-size or line-height arbitrary values without `length:`. Detector rule: `missing-length-type-hint`.
+- `leading-none` combined with `text-[length:var(--*)]`. Detector rule: `leading-none-with-length-var`.
+- Wrong token used: `var(--background)` where `var(--muted)` would have read better; mixing token families.
+- Dark mode visually broken: tokens that look fine in light fail at AAA contrast in dark, or vice versa.
+
+Scoring: 0 = no token usage, 1 = minimal tokens, 2 = partial token coverage with gaps, 3 = good token usage with minor literals, 4 = full token system with verified dark mode.
+
+### 4. Responsive design
+
+Check for:
+
+- Fixed widths that break on narrow viewports.
+- Touch targets below 44 x 44.
+- Horizontal scroll on mobile.
+- Text scaling: layout breaks when the user bumps base font size.
+- Missing or wrong-direction breakpoints (mobile-first vs desktop-first inconsistency in the same component).
+
+Scoring: 0 = desktop-only, 1 = major issues, 2 = partial, 3 = good with minor issues, 4 = fluid across viewports.
+
+### 5. Anti-patterns
+
+Run the deterministic detector against the surface or component:
+
+```bash
+npx seven detect <path>
+```
+
+Then check the report against the Seven rule set:
+
+| Detector rule ID               | Catches                                                                 |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| `non-inter-font`               | Font family other than Inter or JetBrains Mono in consumer code         |
+| `hardcoded-color-not-token`    | Hex, rgb, hsl, OKLCH literal where a token exists                       |
+| `missing-color-type-hint`      | Tailwind v4 arbitrary color value missing the `color:` hint             |
+| `missing-length-type-hint`     | Tailwind v4 arbitrary length value missing the `length:` hint           |
+| `leading-none-with-length-var` | `leading-none` combined with `text-[length:var(--*)]`                   |
+| `fuchsia-in-ui-chrome`         | Fuchsia color on UI chrome (allowed on `data-role="chart"` and `<svg>`) |
+| `pt-pt-vocab`                  | European Portuguese vocabulary in pt-BR surfaces                        |
+| `pure-black-or-white`          | `#000`, `#fff`, `rgb(0,0,0)`, `rgb(255,255,255)` in consumer code       |
+
+Deep detector rules also include `missing-tactile-press`, `radius-mixed-scales`, `pill-on-button`, `forbidden-em-dash`, `gradient-text-decorative`, `side-stripe-border`, `non-lucide-icon`, and `emoji-in-chrome`.
+
+Scoring: 0 = five or more findings, 1 = three or four findings, 2 = one or two findings, 3 = clean detector pass, 4 = clean detector pass plus no additional manual issues evident in review.
+
+## Report shape
+
+For each dimension, write:
+
+```
+### <Dimension> — <score>/4
+
+**Findings**
+- <Finding 1 with file:line reference and detector rule ID when available>
+- <Finding 2>
+
+**Suggested fixes**
+- <Concrete next step keyed to the finding>
+```
+
+End with:
+
+```
+### Overall — <average>/4
+
+Top 3 actions:
+1. ...
+2. ...
+3. ...
+```
+
+## Refusals
+
+- "Just fix the issues you find" — Audit documents, polish fixes. Surface this boundary and offer to invoke `polish` after the audit closes.
+- "Skip the anti-patterns dimension, it always fires" — If anti-patterns always fire on a surface, the surface needs polish, not a softer audit. Run the dimension; record the findings.

package/.claude/skills/seven/reference/brand.md

@@ -0,0 +1,24 @@
+# Brand register (Phase 2 stub)
+
+Loaded when the surface is `brand`: marketing pages, campaign surfaces, long-form content, public-facing landing pages.
+
+## Phase 1 status
+
+Phase 1 of Seven ships with the brand register as a stub. The Seven Design System itself is a product register: app UI, admin, dashboards, internal tools. Brand surfaces in Phase 1 fall back to the shared design laws in `SKILL.md` and the domain references (`typography`, `color-and-contrast`, `spatial-design`, `motion-design`, `ux-writing`).
+
+If the user explicitly requests brand work and `BRAND.md` selects a brand name other than `etus`, Phase 2 will load the matching `reference/brands/<name>.md` here. Phase 2 also adds dedicated brand-register design laws (color strategy, visual direction probes, type display, scene-sentence for theme).
+
+## Bar (Phase 2 target)
+
+Distinctiveness. A brand surface should be recognizably ETUS at a glance, not "a SaaS landing page".
+
+## Defaults expected in Phase 2
+
+- Wider type display lane (Inter Display weights, optical sizes).
+- Maximalist color strategy options (`Committed`, `Full palette`, `Drenched`) instead of the product default `Restrained`.
+- Editorial spacing rhythm (varied, intentional, breathing room).
+- Section-level scene sentences forcing dark vs light per surface, not per project.
+
+## Until Phase 2
+
+Apply the shared design laws and the domain references. Surface to the user that brand-register depth lands in Phase 2 of the port; do not invent Phase 2 features in Phase 1 brand work.

package/.claude/skills/seven/reference/clarify.md

@@ -0,0 +1,76 @@
+# Clarify
+
+Improve UX copy in Seven surfaces. Brazilian Portuguese, sentence case, no trailing periods, imperative leads, plain language. The voice is direct, decisive, brazilian.
+
+## Scope
+
+Clarify rewrites chrome copy: button text, labels, empty states, validation errors, toast messages, menu items, navigation, table column headers, breadcrumbs, tabs, badges, tooltips, dialog titles and descriptions.
+
+Clarify does not rewrite body prose, long-form content, or marketing copy. Those belong to the brand register (Phase 2).
+
+## Rewrite rules
+
+### Voice
+
+- Direct. The label says what the action does. `Adicionar conta`, not `Clique aqui para adicionar uma nova conta`.
+- Decisive. No `talvez`, `poderia`, `seria possível`. If the system suggests an action, it commits.
+- Concrete. Specific over abstract. `Salvo às 14:32` beats `Alterações salvas com sucesso`.
+
+### Case
+
+Sentence case across every chrome surface. Capitalize only the first word and proper nouns. Acronyms (KPI, OTP, OAuth, SSO) stay uppercase.
+
+### Punctuation
+
+- No trailing periods on chrome labels (buttons, menu items, breadcrumbs, table headers, badges, tabs, captions).
+- Periods stay in body prose inside paragraphs.
+- No em-dashes in prose voice. Use periods, commas, or restructure the sentence.
+
+### Language
+
+- Pt-BR for chrome. No pt-PT vocabulary (`ficheiro`, `telemóvel`, `ecrã`, `tu` as pronoun).
+- English only for code identifiers, file paths, API names, and developer-facing technical docs.
+
+## Pattern library
+
+| Surface             | Before (drift)                          | After (Seven)                                      |
+| ------------------- | --------------------------------------- | -------------------------------------------------- |
+| Primary button      | `Clique aqui para salvar.`              | `Salvar`                                           |
+| Primary button      | `Adicionar nova conta`                  | `Adicionar conta`                                  |
+| Destructive button  | `Por favor, excluir esta conta`         | `Excluir conta`                                    |
+| Cancel button       | `Cancelar operação`                     | `Cancelar`                                         |
+| Toast (success)     | `Alterações salvas com sucesso!`        | `Conta atualizada`                                 |
+| Toast (error)       | `Algo deu errado`                       | `Não foi possível salvar. Tente novamente.`        |
+| Empty state         | `Nenhum dado disponível no momento`     | `Nenhuma conta. Adicione a primeira para começar.` |
+| Placeholder         | `Digite o seu email aqui`               | `nome@email.com`                                   |
+| Validation error    | `O campo email é um campo obrigatório.` | `Email obrigatório`                                |
+| Menu item           | `Editar este item.`                     | `Editar`                                           |
+| Table column header | `Nome do usuário.`                      | `Nome`                                             |
+| Tab                 | `Configurações gerais`                  | `Geral`                                            |
+| Badge (status)      | `Ativo no momento`                      | `Ativo`                                            |
+| Breadcrumb          | `Página inicial > Contas`               | `Início › Contas`                                  |
+
+## Numbers, dates, currency
+
+- Numbers: `1.234,56` (Brazilian convention).
+- Dates: `dd/mm/yyyy` in chrome (`12/03/2026`). ISO `2026-03-12` in data tables and logs.
+- Currency: `R$ 1.234,56` with non-breaking space.
+- Relative time for recent events: `há 2 minutos`, `há 1 hora`. Absolute date past 24 hours.
+
+## Workflow
+
+1. List the chrome surfaces in scope (buttons, labels, empty states, errors, toasts).
+2. For each surface, apply the pattern library. Surface anything that does not fit the pattern.
+3. Verify the rewrites against the detector's `pt-pt-vocab` rule:
+
+   ```bash
+   npx seven detect <path>
+   ```
+
+4. Write the rewrites as a diff or table; do not commit until the user confirms.
+
+## Refusals
+
+- "Add 'por favor' to every button to be polite" — Seven voice is direct. Politeness reads as hedging. Buttons are imperatives. Decline politely and explain.
+- "Use English buttons because the team is bilingual" — Pt-BR is the default for chrome. Surface this as a register-layer decision; do not silently switch languages.
+- "Add an em-dash for emphasis in the empty state" — No em-dashes in Seven prose. Restructure the sentence.

package/.claude/skills/seven/reference/color-and-contrast.md

@@ -0,0 +1,84 @@
+# Color and contrast
+
+Seven's color truth lives in `packages/tokens/dist/tokens.css`. Every runtime value is a CSS custom property derived from OKLCH math, never a hex literal.
+
+## Brand colors
+
+- **Mint** — `var(--brand-primary-500)`. The primary brand. Used for primary buttons, active states, focus rings, brand surfaces.
+- **Lime** — `var(--brand-secondary-500)`. The secondary brand. Used for secondary buttons, highlight bars, supporting accents.
+
+Mint and lime are the only brand colors. Do not introduce a third, do not substitute, do not blend.
+
+## Status ramps
+
+Status colors come from the semantic ramps only:
+
+- `var(--destructive)` for errors, destructive actions, deletion confirmations.
+- `var(--warning)` for caution, expiring tokens, soft warnings.
+- `var(--success)` for confirmation, completion, healthy state.
+- `var(--info)` for neutral information.
+
+Do not improvise red, yellow, green, blue values outside these tokens.
+
+## Fuchsia
+
+`#d946ef` style fuchsia is reserved for charts. Never UI chrome. The detector flags fuchsia chroma on buttons, inputs, borders, and other chrome elements; the only allowed habitat is inside `<svg>` and elements tagged `data-role="chart"`.
+
+## Neutrals
+
+Seven neutrals are true grey on the OKLCH ramp. No warm tint, no cool tint, no `oklch(... 0.005 280)` blue-shifted greys that ship as default in some libraries. The ramp goes from `var(--background)` at the top to `var(--foreground)` at the bottom; `var(--muted)`, `var(--muted-foreground)`, `var(--border)` populate the middle.
+
+Pure `#000` and `#fff` are banned. Use the tinted tokens.
+
+## Raw Tailwind palette utilities
+
+Do not use raw Tailwind color utilities in runtime UI (`text-neutral-900`, `bg-green-500`, `border-red-200`, `ring-blue-500`). They bypass the semantic token layer exactly like hex literals do. Use Seven semantic variables instead:
+
+```tsx
+// Correct
+bg-[color:var(--primary)]
+text-[color:var(--primary-foreground)]
+border-[color:var(--border)]
+ring-[color:var(--ring)]
+```
+
+## Tailwind v4 type hints (mandatory)
+
+Tailwind v4 uses Lightning CSS. Lightning requires type hints for ambiguous arbitrary values referencing CSS custom properties. OKLCH colors look like function calls; without a hint, Lightning drops them silently.
+
+```tsx
+// Correct: color: hint on color tokens
+bg-[color:var(--primary)]
+text-[color:var(--primary-foreground)]
+border-[color:var(--border)]
+ring-[color:var(--ring)]
+
+// Correct: length: hint on font-size and line-height tokens
+text-[length:var(--tabs-trigger-base-text)]
+
+// Correct: dimensions, radius, spacing need no hint
+rounded-[var(--radius-md)]
+h-[var(--button-size-md-h)]
+p-[var(--spacing-4)]
+
+// Wrong: no hint, hsl wrapper, or color literal — all drift back to no-op
+bg-[var(--primary)]
+bg-[hsl(var(--primary))]
+bg-[#19e699]
+```
+
+The detector ships `missing-color-type-hint` and `missing-length-type-hint` rules to catch these at scan time.
+
+## Contrast
+
+WCAG 2.1 AA on every component is the baseline. Body text against background hits 4.5:1 minimum; large text 3:1. Verify against the OKLCH math, not by eyeballing the rendered swatch. Pairs to double-check:
+
+- `var(--muted-foreground)` on `var(--background)` — sits on the edge; never use for body copy.
+- `var(--primary-foreground)` on `var(--primary)` — passes for default Seven mint; verify for any brand-layer override.
+- Focus ring color on canvas — must hit 3:1.
+
+## Refusals
+
+- "Make this button orange to draw attention" — Orange is not in the Seven palette. Suggest emphasizing via primary mint plus surrounding lower-contrast siblings, or using `var(--warning)` if the intent is caution.
+- "Use a fuchsia primary for this admin panel" — Fuchsia is chart-only in Seven. Surface the conflict and recommend mint.
+- "Hardcode `#19e699` here because the variable is not loaded" — Variables are always loaded in the consumer; the failure is upstream. Resolve the missing import rather than working around it.

package/.claude/skills/seven/reference/motion-design.md

@@ -0,0 +1,71 @@
+# Motion design
+
+Seven motion is decisive and tactile. No bounce, no spring, no elastic in chrome. The system communicates state through restrained transitions and a system-wide micro-press.
+
+## Defaults
+
+- Duration: `var(--duration-normal)` = 200 ms. Use `var(--duration-fast)` (100 ms) for instant feedback (button press, hover), `var(--duration-slow)` (320 ms) for surface entries (dialog open, sheet slide).
+- Easing: `var(--ease-default)` = `cubic-bezier(0.4, 0, 0.2, 1)` (decelerated). For entries that need a confident finish, use `var(--ease-out-quart)`.
+- Never animate layout properties (`width`, `height`, `top`, `left`). Transform or opacity only; layout animation triggers reflow and looks janky.
+
+## The tactile micro-press
+
+Every clickable affordance in Seven gets the same micro-press, not just `<Button>`:
+
+```css
+.clickable {
+  transition:
+    transform var(--duration-fast) var(--ease-default),
+    box-shadow var(--duration-fast) var(--ease-default);
+}
+.clickable:hover {
+  transform: translateY(-1px);
+}
+.clickable:active {
+  transform: translateY(0.5px);
+  box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.06);
+}
+```
+
+Apply to `<button>`, `<a>` with `role="button"`, the trigger row of `<Combobox>`, the avatar pill in the topbar, table row click affordances, every interactive list item. The detector ships a `missing-tactile-press` rule (Phase 2) that catches affordances that opted out.
+
+Disabled state does not press. Loading state does not press. Reduced-motion users do not press: the entire system honors `prefers-reduced-motion: reduce` and falls back to instant state changes plus an opacity fade.
+
+## Banned motion patterns
+
+- Bounce-back spring on entry. Seven entries decelerate and stop.
+- Elastic overshoot on hover.
+- Wiggle, jiggle, pulse-loop on chrome. Loop animations are reserved for explicit loading indicators (`<Spinner>`).
+- Parallax on product pages. Brand register may use it deliberately.
+- Animated gradient sweeps as decoration.
+
+## Loading and state
+
+- Skeleton screens for content load (rectangles in `var(--muted)`).
+- Inline spinners only when the affordance is itself the loading region (a button mid-submit).
+- Toast for confirmations (success, info), 4 second auto-dismiss, top-right by default.
+- Inline error region for form failures, never a toast.
+
+## Reduced motion
+
+The system honors `prefers-reduced-motion: reduce` site-wide:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    transition-duration: 1ms !important;
+    animation-duration: 1ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}
+```
+
+The tactile micro-press collapses to an opacity step under reduced motion. State changes remain visible, just not animated.
+
+## Refusals
+
+- "Add a bounce when the toast appears" — Seven motion is decelerated, no bounce. Suggest a 200 ms slide-in plus a subtle fade.
+- "Make the button wiggle on hover" — Hover is the tactile press, not a wiggle. Surface this as a deliberate exception or remap to the press.
+- "Animate the card width on resize" — Layout animation reflows. Suggest opacity plus translate transition, or no transition at all.

package/.claude/skills/seven/reference/polish.md

@@ -0,0 +1,55 @@
+# Polish
+
+Final pass on a Seven implementation. Align drift to tokens and conventions. Name the root cause of each fix so the team learns from it, not just patches it.
+
+## Scope
+
+Polish is not greenfield design. The component or surface already exists; this command tightens it to Seven's standards. If the surface is new and incomplete, run `shape` first.
+
+## Three classes of drift
+
+Every polish finding falls into one of three buckets. Name the bucket in your fix description so the user sees the pattern:
+
+1. **Missing token**. The code uses a hex or arbitrary value where a token exists in `@etus/tokens`. Fix: replace literal with `var(--...)` and (for color tokens) add the `color:` type hint.
+2. **One-off implementation**. The code reimplements a component that already exists in `@etus/ui`. Fix: import from `@etus/ui` and delete the local copy. If the local has a needed variant the imported version lacks, flag it as a variant request, do not duplicate.
+3. **Conceptual misalignment**. The code follows shadcn or generic defaults that do not match Seven's identity (purple primary, pill-on-button, em-dash in pt-BR prose, gradient text, glassmorphism). Fix: rewrite to Seven's pattern and document the swap.
+
+## Workflow
+
+1. **Run the detector first**:
+
+   ```bash
+   npx seven detect <path>
+   ```
+
+   The deterministic findings cover token drift and identity-level violations. Address them before manual review.
+
+2. **Read the implementation alongside the matching Figma node.** If there is no Figma node for the variant, flag it as a "variant invented in code" finding; do not silently align to whatever the code already does.
+
+3. **Manual review pass** covering:
+   - Spacing rhythm (vary intentionally; same padding everywhere reads flat).
+   - Border vs shadow hierarchy (borders carry chrome; shadows for overlays only).
+   - Tactile micro-press on every clickable affordance.
+   - 4 px focus ring with 1 px offset on every focusable surface.
+   - Sentence case and no trailing periods on chrome copy.
+   - Pt-BR vocabulary across labels, buttons, empty states, errors.
+
+4. **Write the fix list with root-cause buckets named.**
+
+5. **Apply the fixes** in commit-sized batches:
+   - One commit per logical fix family (all token replacements, all variant consolidations, all copy fixes).
+   - Conventional commit messages, lowercase subject (Seven commit rule).
+   - Tests pass before each commit.
+
+## What polish never does
+
+- Add new variants that do not exist in Figma. Surface the gap, do not invent.
+- Refactor unrelated code because it "looks bad". Surgical changes only.
+- Change public component APIs. If a prop should change, that is a separate proposal, not polish.
+- Touch `packages/tokens/sources/`. Token changes flow from Figma via the figma-sync skill, not from polish.
+
+## Refusals
+
+- "Refactor the whole file while you are in there" — Polish is surgical. Document the additional issues as a follow-up, do not bundle them.
+- "Add a fancy hover state to make it pop" — Seven hover is the tactile press. Adding decorative hover is drift. Surface and decline.
+- "Replace the import with a custom component because the variant is missing" — That is a Figma variant request. Document it, ask the user, do not duplicate.

package/.claude/skills/seven/reference/product.md

@@ -0,0 +1,45 @@
+# Product register
+
+Loaded when the surface is `product`: app UI, admin, dashboards, settings, internal tools. The default for Seven.
+
+## Bar
+
+Earned familiarity. A fluent user of Linear, Figma, Notion, Raycast, or Stripe Dashboard should trust the surface within five seconds. That trust is built from consistent affordances, predictable spacing, and tactile feedback, not from cleverness.
+
+## Defaults
+
+When in doubt:
+
+- Card-on-canvas layouts with the workhorse 1 px `var(--border)`. Shadows only on overlays.
+- Two-column or sidebar-and-detail shells. Avoid wide single-column dashboards.
+- Density: comfortable, not compact. Buttons are 36 px medium by default, inputs match.
+- States exposed by border or surface tint, not by motion. Loading is a skeleton; success is an inline confirmation; error is inline plus a destructive border on the offending field.
+
+## Iconography
+
+- Lucide only. 2 px stroke, round caps, `currentColor`. Filled variants only where Lucide ships them.
+- Icon size matches the line-height of the adjacent text (16 px next to body, 20 px next to headings).
+- No emoji in chrome. No Unicode dingbats. No legacy Material icons.
+- Custom SVGs match the Lucide stroke and cap conventions or they are not Seven icons.
+
+## Affordances
+
+Every clickable surface — `<button>`, `<a>`, `[role="button"]`, the trigger of a `<Popover>`, the row of a `<Combobox>` — picks up the tactile micro-press system-wide. Hover translates 1 px up, active translates back down, an inset shadow confirms the press.
+
+Focus ring is 4 px on the focus token color, with a 1 px offset against the canvas. Never use the browser default `outline`.
+
+Disabled state: muted foreground, no pointer cursor, no tactile press, no focus ring.
+
+## Refusals
+
+Surface the conflict, do not silently comply.
+
+- "Make this a single big primary button" on a dashboard with three primary actions — explain the visual hierarchy cost and recommend a single primary plus two secondary, or a split button.
+- "Add a glow under the active row" — Seven does not use glow on chrome. Recommend a brand-tinted background or a left-accent rule that is part of the row's structure, not a decorative halo.
+- "Show this metric in a gradient" — Seven prose forbids gradient text. The metric belongs in a solid `var(--foreground)` with hierarchy from scale and weight.
+
+## Sub-commands that apply
+
+All four Phase 1 sub-commands (`shape`, `audit`, `polish`, `clarify`) apply to product surfaces.
+
+For Phase 2 brand register surfaces, load [reference/brand.md](brand.md) instead. The shared design laws in `SKILL.md` apply to both.