@fracazo/design-system 0.2.1 → 0.7.0

package/skills/product-design/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: product-design
+description: >-
+  Single entry point for product design and user-facing implementation in a
+  product built on @fracazo/design-system. Use whenever work changes what a
+  reader sees, understands, chooses or does: shaping a flow, building or
+  restyling a page or component, reviewing a route, screenshot or diff,
+  improving copy, hierarchy, layout, interaction, accessibility, responsive
+  behaviour or loading, empty, error and destructive states. Trigger on
+  design, UX, UI, layout, styling, tokens, colour, type, spacing, motion,
+  copy, polish, audit, review, accessibility, dark mode, mobile. Not for
+  backend-only work, telemetry, generated files, or tests with no shipped UI.
+---
+
+# Product design on @fracazo/design-system
+
+Make the surface correct for the reader, the product and the system. Working
+code is not enough: choose the right composition, spend emphasis once, cover
+the states the product can really enter, and verify the rendered result in
+both themes. The stylesheet and the lint do the visual work; this skill
+carries the judgment and the reasons.
+
+## Operating contract
+
+- **Start with the reader's job, not the pixels.** Who is reading, on what
+  device, under what pressure, and what they must decide or do here.
+- **Name the surface scope first.** Engagement (the product) or conversion
+  (landing, guides). Budgets, imagery and motion rules differ. See
+  `references/surfaces.md`.
+- **Use evidence, not taste.** Trace a decision to a rule in
+  `references/rules.md`, a section of `DESIGN.md`, a component's intent
+  block, or an exemplar. Shipped code proves what exists, not that it is
+  right.
+- **Decide before decorating.** Composition, component choice and states
+  before colour, radius or copy.
+- **Spend emphasis once.** One focal relationship per screen. When a surface
+  shouts, remove signals; never add a louder one.
+- **Values live in tokens.** Never a colour, radius or fluid size literal in a
+  className. A missing value is a proposal for the design-system repo.
+- **Verify the real surface.** Source inspection establishes behaviour; a
+  rendered page in light and dark establishes quality. Token work runs the
+  product's snapshot compare.
+- **Keep one entry point.** Load this file; route to the references below.
+  Do not paste their content into answers; cite the rule ID or section.
+
+## Request modes
+
+Resolve the mode from the verb before acting. Use the narrowest mode the
+verb supports. A URL, screenshot or route sets scope; it does not authorise
+edits.
+
+| Mode | Typical request | Required behaviour |
+|---|---|---|
+| Shape | "Design this flow", "how should this work?" | Frame reader, job, evidence; compare material alternatives; define flow, states, acceptance criteria and open decisions. No edits unless asked. |
+| Implement | "Build", "fix", "improve", "make it compliant" | Resolve material decisions, then the smallest coherent end-to-end change. Do not absorb unrelated findings. |
+| Review | "Audit", "critique", "what's wrong?" | Inspect source and rendered evidence; report prioritised findings with rule IDs. No edits unless asked. |
+| Copy | "Fix the copy", "rewrite this error" | Edit user-facing language and accessible names only. Report structural blockers; do not widen scope. |
+| Harden | "Polish", "production-ready", "edge cases" | Keep the settled direction; fix state, resilience, responsive, accessibility and finish defects. |
+
+A material decision changes the reader's task, default, consequence,
+navigation, interaction surface or reachable states. Token substitution and
+established component swaps are not material.
+
+## Decision authority
+
+Resolve conflicts in this order.
+
+1. The user's explicit goal and constraints.
+2. Verified product behaviour and system truth (what the tokens and
+   components actually do).
+3. The product's CLAUDE.md, then this skill's `references/rules.md`,
+   `DESIGN.md`, `css/roles.css` and the component intent blocks.
+4. Exemplars with stable evidence (`exemplars/`).
+5. Verified adjacent shipped patterns in the same product area.
+6. General interface heuristics.
+
+## Workflow
+
+1. **Set scope and mode.** Name the product, the route or component, the
+   surface scope and the mode.
+2. **Load product context.** The product's CLAUDE.md design section, the
+   brand file, the product chapter in `DESIGN.md`, and the code that
+   decides what the surface can show.
+3. **Model the decision** (Shape, Implement, Harden, full Review). Reader,
+   job, current behaviour, desired outcome, success signal, non-goals,
+   consequence, reversibility, open decisions. Keep it compact.
+4. **Map the surface and states.** Entry points, regions, overlays,
+   transitions, exits. Only reachable states: loading, empty, populated,
+   validation, error, disabled, optimistic, destructive, both themes,
+   360px and 1280px.
+5. **Load the routed references.**
+
+   | Need | Load |
+   |---|---|
+   | Any styling or token decision | `references/tokens.md` |
+   | Sizes, radius, spacing, rhythm | `references/type-and-space.md` |
+   | Hover, entrance, transitions, reduced motion | `references/motion.md` |
+   | Which component, house patterns | `references/components.md` + the component's intent block |
+   | Copy, labels, errors, English variant | `references/copy.md` |
+   | Which surface, budgets, imagery | `references/surfaces.md` |
+   | Any rule by ID, lint status, examples | `references/rules.md` |
+   | Before claiming zero visual change | `references/verification.md` |
+   | Running or judging an intake packet | `references/intake.md` |
+
+6. **Decide, then implement.** For each non-mechanical change be able to
+   say: what reader problem it solves, why this component, what consequence
+   the surface must communicate, which rule or exemplar supports it, and
+   what the smallest coherent change is.
+7. **Verify.** Lint (`pnpm lint`), typecheck, both themes, compact and wide
+   viewports, keyboard order and focus, every materially changed state, long
+   content. Token work: snapshot compare, delta stated.
+
+## Review output
+
+Lead with findings, ordered by reader impact.
+
+- **P0** blocks the primary task, severe accessibility failure, or harm the
+  reader cannot undo.
+- **P1** likely task failure, misleading consequence, missing critical
+  state, major responsive or accessibility defect.
+- **P2** meaningful friction, weak hierarchy, inconsistency, recoverability.
+- **P3** minor craft.
+
+Each finding: location (file and line, or rendered), verification status
+(seen rendered, inferred from source), rule ID or source, reader
+consequence, smallest concrete fix.
+
+## Skill integrity
+
+- Add or change a rule only after the same correction has recurred and a
+  human has accepted it. One screenshot, one file or one review comment is
+  never a rule by itself.
+- Record scope, rule, why, exceptions, source and a bad and good example
+  (`references/rules.md` format).
+- Prefer the narrowest destination: a token or contract entry, a lint rule,
+  a rule record, an exemplar, or a coverage gap. Deterministic checks stay
+  mechanical; judgment stays in prose with its evidence.
+- New evidence enters through the intake loop (`references/intake.md`):
+  `ds-intake` collects, the agent proposes in the packet, a human reviews
+  and accepts.
+- Keep `coverage-gaps.md` honest. A missing rule is not a licence to invent
+  one; it is a decision to raise.

package/skills/product-design/coverage-gaps.md

@@ -0,0 +1,41 @@
+# Coverage gaps
+
+Decisions we do not have a standard for yet, and rules that exist in prose
+but could be code. A gap is a decision to raise, not a licence to invent.
+
+## Lint candidates (checkable by code, not written)
+
+Shipped in 0.4.0 as `design-system/*` rules: no-colour-literal,
+no-arbitrary-clamp, no-dark-pairs, no-radius-literal, no-stock-palette,
+focus-visible, on-dark-ramp, no-em-dash. Still candidates:
+
+- A `className` on a package component that overrides its colour, radius or
+  shadow (layout classes allowed). Needs the imported component names.
+- rule/no-dark-pairs, second form: a `dark:` token utility beside its light
+  twin (`bg-band dark:bg-dark`), which usually means a missing token.
+- rule/voice-bans as a word list over string literals in JSX.
+- Warnings to turn into errors once each product is clean: no-stock-palette
+  (BirthGuide 48, birthplans 5), focus-visible (24, 2), no-em-dash (47, 23).
+
+## Missing decisions
+
+- Loading, empty and error state patterns for engagement surfaces beyond
+  optimistic writes: no written standard; each product improvised.
+- Destructive action wording and confirmation shape: not standardised
+  (current usage: the questionnaire discard flow, plan deletion).
+- Toast or inline confirmation after a save: no standard.
+- Form validation timing (on blur, on submit) and error placement: follow
+  the package's FormMessage, but no written rule.
+- A house table treatment: none; the price tracker and calculators each
+  built their own.
+- Illustration style for conversion surfaces: the brand spec's guidance
+  predates the warm palette and names colours that are not in production.
+- birthplans.app type-role pass: fourteen clamp literals await convergence
+  before its fluid-type lint can switch on.
+- Whether a product may ship a manual theme toggle: today, none do, by
+  decision; not recorded as a rule.
+
+## Evals
+
+None yet. When the exemplars reach ten, build before and after fixtures
+from them and hold two out.

package/skills/product-design/exemplars/calm-the-offering-cards.md

@@ -0,0 +1,33 @@
+# Exemplar: calm the offering cards
+
+Status: accepted
+Product: BirthGuide, landing hero offering pair
+Source: BirthGuide commit "feat(landing): calm the offering cards down"
+Rules: rule/one-emphasis-signal, rule/concentric-radii, rule/semantic-first
+
+## Decision
+
+The two hero cards carried four emphasis signals at once: a tinted border,
+a heavy drop shadow, a bold uppercase chip and an accent CTA. Cut to the
+chip and the CTA. Both cards moved onto the same hairline and the same soft
+shadow, and onto the treatment the testimonial cards already used
+(`rounded-20 p-7 shadow-warm-sm`). Type and ornament came down with it:
+icon tiles 54px to 40px, title capped at 24px, the accent semibold tagline
+became a muted caption, accent ticks became muted dots. The comparison band
+took the same surface so the two pairs still read as siblings.
+
+## Why it matters
+
+Emphasis is a budget. When everything on a card is loud, nothing is. The
+fix was subtraction and reuse of an existing surface, not a new style.
+
+## Repeat
+
+- Count the signals on a surface before styling it. If more than one, remove.
+- Borrow the surface an adjacent component already uses before inventing one.
+- Bring siblings along so a calmer card does not look like the odd one out.
+
+## Avoid
+
+- Answering "this card does not stand out" with a stronger border or shadow.
+- A new radius, shadow or tint for one card.

package/skills/product-design/exemplars/clamp-drift-to-named-roles.md

@@ -0,0 +1,37 @@
+# Exemplar: converge near-miss clamp drift onto named roles
+
+Status: accepted
+Product: BirthGuide landing, then the package's type roles
+Source: BirthGuide commits "refactor(design): name the fluid type and band rhythm tokens", "fix(landing): converge near-miss clamp drift onto the named tokens", "feat(lint): guard arbitrary fluid type sizes in className"
+Rules: rule/no-arbitrary-clamp
+
+## Decision
+
+A typography audit found five bespoke h1 clamps, eight section-title
+clamps and seven lede clamps, most within a pixel or two of each other.
+The exact current hero scale became `text-display` (byte-identical, with
+its 0.9 line-height companion); section titles and ledes converged onto
+`text-section-title` and `text-lede`, with two approved rewraps checked
+from renders (lede cap 20px to 19px, guides gap 48px to 52px). The final
+CTA kept its bespoke 62px clamp by decision, as did the benched sections
+and the mobile-link h1; each carries an inline disable with the reason.
+Then the lint rule went on so no new clamp literal lands.
+
+## Why it matters
+
+Near-miss sizes are invisible drift: nobody can say which of eight almost
+identical clamps is the intended one. Naming the role settles it, and the
+lint keeps it settled. The deliberate one-offs stay visible in review
+because the disable states why.
+
+## Repeat
+
+- Name the role at the exact current value first (zero change), then
+  converge the near misses in a separate, render-reviewed step.
+- Turn the lint on only after the codebase is clean or every exception is
+  disabled with a reason.
+
+## Avoid
+
+- Converging by eye in one pass with the rename.
+- Silencing the rule file-wide.

package/skills/product-design/exemplars/concentric-radii-and-button-optics.md

@@ -0,0 +1,36 @@
+# Exemplar: craft pass, concentric radii and button optics
+
+Status: accepted
+Product: BirthGuide, then the package's Button
+Source: BirthGuide commits "feat(design): craft pass tier 1: tabular numerals, concentric radii, button optics", "feat(ui): move button primitive from pill to size-scaled rounded-rect" (SPEC_021)
+Rules: rule/concentric-radii, rule/no-radius-literal
+
+## Decision
+
+Exact-token radius renames first (`rounded-[26px]` to `4xl`,
+`rounded-[14px]` to `xl`, `rounded-[10px]` to `lg`), zero rendering change.
+Then concentric corners where a rounded child meets a rounded parent, each
+landing on a named token. Tabular numerals on five column surfaces only;
+headline figures stayed proportional. Buttons moved from pills to rounded
+rectangles on a size-scaled corner ladder so a flush button can go
+concentric with its container, and only the icon side of a button tightens
+so icon-plus-text reads centred (the primitive wraps bare text in a span so
+CSS can tell which side the icon is on).
+
+## Why it matters
+
+The snapshot harness compared identical on all 311 covered keys, which
+proved no incidental drift; the intended changes sat below the tool's
+resolution and were reviewed as source diff plus live probes. Craft work
+and refactor work were separated so each could be verified its own way.
+
+## Repeat
+
+- Split exact renames (identical snapshot) from intended changes (reviewed
+  renders), even inside one spec.
+- Apply the concentric formula only where corners meet.
+
+## Avoid
+
+- Tabular numerals everywhere; they are for columns.
+- A pill button inside a rounded card; the corners can never be concentric.

package/skills/product-design/exemplars/dialog-close-focus-visible.md

@@ -0,0 +1,36 @@
+# Exemplar: dialog close ring only for keyboard users
+
+Status: accepted
+Product: BirthGuide, now the package's Dialog
+Source: BirthGuide commit "fix(ui): show the dialog close ring only for keyboard users"
+Rules: rule/focus-visible
+
+## Decision
+
+Three PDF-preview modals showed a focus ring on their close button when
+opened with a mouse; the birth-webpage preview did not. The modals were the
+same component. Radix autofocuses the first focusable element on open, and
+the close button carried `focus:ring-2`, so the ring painted wherever the
+dialog body had no controls of its own. Switching to `focus-visible:`
+removed the ring for pointer users on every dialog and kept it for
+keyboard users. Verified both ways: after a click the computed box-shadow
+was none; after Shift+Tab the button matched `:focus-visible` and rendered
+the brand ring.
+
+## Why it matters
+
+The reader saw a mystery highlight on a button they had not touched. It
+looked like a bug and it was one, in the shadcn default. The comment above
+the element records the reason because `shadcn add dialog` reverts it.
+
+## Repeat
+
+- Measure before changing: the two modals were compared property by
+  property and only the focused element differed.
+- Verify accessibility fixes in both directions, pointer and keyboard.
+- Write the reason next to a deliberate deviation from a generator's default.
+
+## Avoid
+
+- Fixing one modal. The component is shared; fix it once, upstream.
+- Removing the ring for everyone.

package/skills/product-design/exemplars/hero-glow-seam.md

@@ -0,0 +1,34 @@
+# Exemplar: blend the hero glow into the next section
+
+Status: accepted
+Product: BirthGuide, landing hero to curriculum boundary
+Source: BirthGuide commit "fix(landing): blend the hero glow into the curriculum section"
+Rules: rule/no-clipped-ambient
+
+## Decision
+
+The hero's ambient glow layer kept `overflow-hidden` because its blobs sit
+past the left and right edges, but the same clip sat at `bottom-0` and cut
+the second blob flat at the hero's last pixel. Measured at 1280x800, the
+boundary carried a luminance step of 16.99 in dark and 5.63 in light,
+exactly on the row where the sections meet. Three changes together: the
+layer extends 280px past the bottom (blob offset plus blur), a mask
+dissolves the overhang across that distance, and the next section takes
+`relative z-10` so the glow paints behind its content.
+
+## Why it matters
+
+A hard horizontal seam between sections is the kind of defect nobody can
+name but everyone feels. It was invisible in source and obvious once
+measured on the rendered page.
+
+## Repeat
+
+- Verify ambient effects rendered, at the seam, in both themes; measure the
+  luminance step if unsure.
+- Extend the clip past blob plus blur, then mask; do not just remove the clip.
+- Give the following section a stacking context so the overhang stays behind.
+
+## Avoid
+
+- Shrinking or moving the blob to dodge the clip; the composition changes.