From e5bd6452f5d1dca21780640eec9603d2d97071a0 Mon Sep 17 00:00:00 2001 From: myypo Date: Sat, 3 Oct 2026 10:29:43 +0300 Subject: [PATCH] feat: sync cheers-design with impeccable 4.5.0 Port upstream Impeccable 508d7e89 into skills/cheers-design without the upstream binary: * replace the brand/product registers with Persuade, Operate, Read and Experience visitor modes (product.md becomes operate.md, brand.md folds into modes.md) * add craft-floor, new-work, modes, routing and finish-review references; craft becomes a deprecated alias for new-work * run the direction round by hand instead of concept-seed, store surface briefs under .cheers-design/surfaces/, and hand finished builds to a fresh reviewer subagent * rewrite the command references around visitor modes, isolated design assessments, an optional `impeccable detect` scan and bounded verification passes, with touch-gesture checks * follow the eight-section DESIGN.md spec and drop Register from PRODUCT.md * make critique snapshot names unique to the millisecond, include the port in URL slugs and warn on invalid metadata Live mode, variant generation, image comps, hooks, doctor and native iOS/Android guidance are not ported. --- NOTICE.md | 2 +- skills/cheers-design/NOTICE.md | 5 +- skills/cheers-design/SKILL.md | 97 +++++--- skills/cheers-design/reference/adapt.md | 105 ++++++--- skills/cheers-design/reference/animate.md | 116 ++++++---- skills/cheers-design/reference/audit.md | 149 +++++++------ skills/cheers-design/reference/bolder.md | 82 ++++--- skills/cheers-design/reference/brand.md | 75 ------- skills/cheers-design/reference/clarify.md | 113 ++++++---- skills/cheers-design/reference/colorize.md | 105 ++++++--- skills/cheers-design/reference/craft-floor.md | 49 +++++ skills/cheers-design/reference/craft.md | 103 +-------- skills/cheers-design/reference/critique.md | 208 +++++++++++------- skills/cheers-design/reference/delight.md | 93 +++++--- skills/cheers-design/reference/distill.md | 90 +++++--- skills/cheers-design/reference/document.md | 184 ++++++++++------ skills/cheers-design/reference/extract.md | 97 ++++---- .../cheers-design/reference/finish-review.md | 41 ++++ skills/cheers-design/reference/harden.md | 146 +++++++----- skills/cheers-design/reference/init.md | 111 ++++++---- skills/cheers-design/reference/layout.md | 95 ++++---- skills/cheers-design/reference/modes.md | 81 +++++++ skills/cheers-design/reference/new-work.md | 139 ++++++++++++ skills/cheers-design/reference/onboard.md | 101 ++++++--- skills/cheers-design/reference/operate.md | 65 ++++++ skills/cheers-design/reference/optimize.md | 111 ++++++---- skills/cheers-design/reference/overdrive.md | 70 +++--- skills/cheers-design/reference/polish.md | 107 +++++---- skills/cheers-design/reference/product.md | 66 ------ skills/cheers-design/reference/quieter.md | 89 +++++--- skills/cheers-design/reference/routing.md | 30 +++ skills/cheers-design/reference/shape.md | 98 +++++---- skills/cheers-design/reference/typeset.md | 89 ++++---- .../scripts/critique-storage.mjs | 12 +- 34 files changed, 1930 insertions(+), 1194 deletions(-) delete mode 100644 skills/cheers-design/reference/brand.md create mode 100644 skills/cheers-design/reference/craft-floor.md create mode 100644 skills/cheers-design/reference/finish-review.md create mode 100644 skills/cheers-design/reference/modes.md create mode 100644 skills/cheers-design/reference/new-work.md create mode 100644 skills/cheers-design/reference/operate.md delete mode 100644 skills/cheers-design/reference/product.md create mode 100644 skills/cheers-design/reference/routing.md diff --git a/NOTICE.md b/NOTICE.md index 5e3795b..01f9dfd 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -9,7 +9,7 @@ Package-local notices and license texts are kept next to the code or skill mater `skills/cheers-design` adapts material from Impeccable. - Original work: -- Upstream sync/base: `f636bd065a11234bfc7f1b0e0cd9d1ba7a0eb209` +- Upstream sync/base: `508d7e8955de3b3caf2d8676e85206723d41a887` - Copyright: 2025-2026 Paul Bakaus - License: Apache License 2.0 - Local notice: [`skills/cheers-design/NOTICE.md`](skills/cheers-design/NOTICE.md) diff --git a/skills/cheers-design/NOTICE.md b/skills/cheers-design/NOTICE.md index c1e37b3..29228b6 100644 --- a/skills/cheers-design/NOTICE.md +++ b/skills/cheers-design/NOTICE.md @@ -6,9 +6,10 @@ This skill adapts material from Impeccable. - Copyright: 2025-2026 Paul Bakaus - License: Apache License 2.0 - License text: [`LICENSES/impeccable-Apache-2.0.txt`](LICENSES/impeccable-Apache-2.0.txt) -- Changes: adapted the design-skill guidance for Cheers/Rust/Datastar, added a clear boundary with the main `cheers` implementation skill, kept only design-level interaction guardrails such as backend-confirmed state and no optimistic UI, migrated setup language to `init`, added critique snapshot persistence under `.cheers-design/critique/`, and adopted Google Stitch-style `DESIGN.md` frontmatter guidance. +- Upstream sync/base: `508d7e8955de3b3caf2d8676e85206723d41a887` +- Changes: adapted the design-skill guidance for Cheers/Rust/Datastar, added a clear boundary with the main `cheers` implementation skill, kept only design-level interaction guardrails such as backend-confirmed state and no optimistic UI, migrated setup language to `init`, added critique snapshot persistence under `.cheers-design/critique/`, and adopted Google Stitch-style `DESIGN.md` frontmatter guidance. The new-work flow, visitor modes, craft floor, and finish review are reworked to run without the upstream `impeccable` binary: direction rounds are run by hand instead of the concept-seed roll and decision page, surface briefs live under `.cheers-design/surfaces/`, the finish reviewer is a generic subagent prompt, and the `impeccable detect` scan is optional. Live mode, variant generation, image comps, hooks, doctor, and native iOS/Android guidance are not included. -Upstream Impeccable `NOTICE.md` attribution is reproduced below: +Upstream Impeccable `NOTICE.md` attribution, as published at upstream commit `f636bd065a11234bfc7f1b0e0cd9d1ba7a0eb209` (the previous sync base), is reproduced below. The current upstream `NOTICE.md` only attributes the iOS and Android platform references, which this skill does not include. ```text # Notice diff --git a/skills/cheers-design/SKILL.md b/skills/cheers-design/SKILL.md index 380dfc2..e96e799 100644 --- a/skills/cheers-design/SKILL.md +++ b/skills/cheers-design/SKILL.md @@ -1,36 +1,55 @@ --- name: cheers-design -description: "Use when a Cheers task requires UI/UX design judgment: shaping a new visible surface, materially changing layout, hierarchy, copy, interaction states, motion, onboarding, or requested design audit/polish." -argument-hint: "[init|document|shape|craft|extract|critique|audit|polish|harden|optimize|clarify|adapt|onboard|layout|typeset|colorize|bolder|quieter|distill|delight|animate|overdrive] [target]" +description: "Use when a Cheers task requires UI/UX design judgment: building a new visible surface, redesigning or materially changing layout, hierarchy, copy, interaction states, motion, onboarding, or requested design critique, audit, or polish." +argument-hint: "[init|teach|document [--seed]|shape|craft|extract|critique|audit|polish|harden|optimize|clarify|adapt|onboard|layout|typeset|colorize|bolder|quieter|distill|delight|animate|overdrive] [target]" user-invocable: true --- # Cheers Design -Design and iterate production-grade interfaces for Cheers apps. This skill owns UX, visual direction, interaction design, content, accessibility, state coverage, and design-system judgment. The main `cheers` skill owns the technical Cheers/Rust/Datastar implementation rules. +Design and iterate production-grade interfaces for Cheers apps. Approach every task as a design director with a clear point of view, deep understanding of the client and users, and exceptional craft: safe, timid, average work is the failure mode. This skill owns UX, visual direction, interaction design, content, accessibility, state coverage, and design-system judgment. The main `cheers` skill owns the technical Cheers/Rust/Datastar implementation rules. -## Required setup +Core principles: + +- **Go all out.** The deliverable is complete, except assets only the user can provide. +- **Dream big.** Distinct, specific, inspiring work over the category default. +- **Verify in bounded passes, not a loop.** The ceiling covers the whole cycle: screenshots, scans, micro-edits, and rebuilds alike. Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop. Open-ended self-QA spends the user's time doing worse what a fresh review does better. + +## Setup Before design work or file edits: 1. If the task involves code edits and `cheers` is not already loaded, read it for implementation mechanics. Do not duplicate those mechanics here. -2. Read existing `PRODUCT.md` and `DESIGN.md` when present. If they are missing and the task depends on strategic context, use `init` or `document` rather than inventing a brand or system. -3. Classify the surface as **product** or **brand**, then read the matching register reference: - - [reference/product.md](reference/product.md) for authenticated app UI, dashboards, settings, tools, forms, and data surfaces. Design serves a task. - - [reference/brand.md](reference/brand.md) for landing pages, marketing, long-form, portfolio, campaign, public storytelling. Design is the product. -4. If a sub-command is used, read its reference file from `reference/`. -5. Inspect the target app's visible UI, source, components, styles, content, state coverage, tests, and conventions before changing code. -6. State the interaction contract before implementation at design level: normal navigation, backend-confirmed action, local affordance signal, stream, server-pushed script, or static JS helper. +2. Read existing `PRODUCT.md`, `DESIGN.md`, and the target's surface brief in `.cheers-design/surfaces/` (see [new-work.md](reference/new-work.md#5-record-the-decision)) when present. Do not invent missing context. +3. Load the request's playbook: its Commands-table reference for an explicit or implied sub-command, or [reference/new-work.md](reference/new-work.md) for a new surface or replacement visual world. Inspect the target and the incumbent visual truth (running app, templates, CSS, tokens, components, assets) before editing. When the app cannot run, start from committed visual-regression goldens or screenshot fixtures; check they are current against tokens, CSS, components, and assets, resolve conflicts, and compare theme or variant captures. +4. Choose the surface's visitor mode (below) and, for Operate or Read surfaces, read [reference/operate.md](reference/operate.md). +5. State the interaction contract at design level before implementation: normal navigation, backend-confirmed action, local affordance signal, stream, server-pushed script, or static JS helper. +6. After analysis and direction are settled, read [reference/craft-floor.md](reference/craft-floor.md) immediately before any UI edit, including small refinements. Do not load it for planning-only work. + +## How to design + +- **The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning. Redirecting a clear brief toward your taste is failure. +- **Refinement preserves; redesign replaces.** Refinement keeps the incumbent identity, behavior, copy, and everything outside scope. Ask before replacing factual copy or adding claims. Redesign keeps product truth, content, function, native affordances, and constraints, but treats the old look as evidence and anti-reference: choose a replacement world in new-work and replace DESIGN.md. Never split the difference into polish on the discarded look. +- **Visual authority is evidence, not a filename.** A missing DESIGN.md alone does not make a project greenfield; new-work decides whether to preserve, expand, or replace the incumbent world. + +## Visitor modes + +The mode names what the visitor's success looks like on this surface. -If the task is visually open-ended, use `shape` first. Do not implement an unconfirmed major direction unless the user explicitly asks you to proceed without a separate brief. +- **Persuade:** the visitor decides and acts; design is the product. Landing pages, marketing, campaigns, pricing. Earn attention and action. Ship real imagery when the brief needs it; follow the committed world, not category habit. +- **Operate:** the visitor completes a task. App UI, dashboards, editors, admin, settings, tools. Scanability, consistency, familiar affordances, and the real usage scene outrank expression. Brand lives in precise details. +- **Read:** the visitor understands something. Docs, articles, guides, help, changelogs. Structure for comprehension, then make the reading experience worth staying in. +- **Experience:** the visitor is inside the work itself. Portfolios, galleries, showcases. Let the artifact lead from the first viewport; the interface recedes. + +Choose the mode from the requested surface, not the product, and persist it only in that surface brief. A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade. See [modes.md](reference/modes.md) for how far each mode lets a visual world reach, and [operate.md](reference/operate.md) for Operate and Read depth. ## Skill boundary Use this skill to decide: - user purpose, primary action, information architecture, and flow -- register, theme, visual direction, hierarchy, composition, typography, color, motion, and imagery -- empty, loading, pending, error, success, permission, overflow, mobile, and first-run states +- visitor mode, visual world, hierarchy, composition, typography, color, motion, and imagery +- empty, loading, pending, error, success, permission, overflow, mobile, touch, and first-run states - labels, microcopy, status messages, help text, and recovery copy - design-system alignment, reusable UI patterns, and visual quality bar @@ -49,38 +68,43 @@ These are design constraints, not a duplicate implementation manual. ## Shared design laws -Apply these without fighting the Cheers interaction guardrails. +The craft floor holds the mechanical checks and bans. These laws hold the judgment: - Start with user purpose, content, states, constraints, and primary action before layout or styling. -- Product UI should feel trustworthy, consistent, task-focused, and familiar where familiarity helps. See [product.md](reference/product.md). -- Brand UI needs a point of view. Typography, imagery, composition, and color should feel specific, not generated. See [brand.md](reference/brand.md). - Pick a color strategy before values: Restrained, Committed, Full palette, or Drenched. Use OKLCH when possible; tint neutrals rather than defaulting to pure black, pure white, or flat gray. - Choose light or dark from a scene sentence: who uses this, where, under what ambient light, in what mood. Do not default by category. -- Use typography for hierarchy and voice. Keep prose around 65-75ch; avoid flat type scales. -- Vary spacing for rhythm. Same padding everywhere is monotony. Cards are not a default container, and nested cards are a design smell. -- Motion must clarify hierarchy, feedback, loading, reveal, or transition. Respect reduced motion and do not animate layout casually. -- Use real content over placeholders. Handle empty, loading, pending, error, success, overflow, long text, permissions, and first-run states. -- Every word earns its place. Avoid repeated headings, filler claims, vague button labels, em dashes in product copy, and status text that overpromises. -- Avoid generic AI tells: gradient text, decorative glassmorphism, nested cards, endless equal card grids, hero metric blocks, side-stripe card accents, modal-first flows, redundant copy, and category-reflex palettes. -- Run the category-reflex check: if the theme, palette, typography, or layout could be guessed from the product category alone, rework the visual direction. +- Use typography for hierarchy and voice. Vary spacing for rhythm; same padding everywhere is monotony. +- Motion must clarify hierarchy, feedback, loading, reveal, or transition. Respect reduced motion. +- Use real content over placeholders. Every word earns its place; avoid filler claims, vague button labels, em dashes in product copy, and status text that overpromises. +- Run the category-reflex check: if the theme, palette, typography, or layout could be guessed from the product category alone, or from category-plus-avoidance, rework the direction. - Keep examples and implementation advice in Cheers/Rust/Datastar terms when code is needed, but prefer referencing `cheers` over repeating syntax here. +## Mechanical scan (optional) + +Command references pair their design assessment with a mechanical anti-pattern scan. Upstream Impeccable's `impeccable detect` can scan a running Cheers app by URL; it cannot read Rust `html!` templates, so point it at the rendered page or at stylesheet files. + +- If `impeccable` is on `PATH`, run `impeccable detect --json [--scope type|layout] ` against the dev server. Add `--viewport 390x844` for a mobile pass. It drives an installed Chrome or Chromium. Exit 0 means clean, 2 means findings, 1 means a target could not be scanned. +- If only `npx` is available, ask before running `npx impeccable detect`, since it downloads a package. +- Otherwise, or when the dev server is not running, run the scan by hand: check the rendered page and source against [craft-floor.md](reference/craft-floor.md)'s Refuse list and Verify checks. + +Run the design assessment before reading scan results so findings do not anchor it, and synthesize both before editing. A clean scan is a floor, not proof of quality. Never block a task on the scan. + ## Commands | Command | Use | Reference | |---|---|---| -| `init` | Capture strategic product/brand context in PRODUCT.md and set up design docs | [reference/init.md](reference/init.md) | -| `document` | Create or refresh DESIGN.md from Cheers UI code | [reference/document.md](reference/document.md) | -| `shape [target]` | Produce a task-specific UX/UI brief before code | [reference/shape.md](reference/shape.md) | -| `craft [target]` | Build a confirmed brief into Cheers code and iterate | [reference/craft.md](reference/craft.md) | +| `init` (alias `teach`) | Capture durable product truth in PRODUCT.md | [reference/init.md](reference/init.md) | +| `document [--seed]` | Create or refresh DESIGN.md from Cheers UI code; `--seed` records a direction before code exists | [reference/document.md](reference/document.md) | +| `shape [target]` | Plan UX/UI as a confirmed brief before code | [reference/shape.md](reference/shape.md) | +| `craft [target]` | Deprecated alias for an ordinary new-work request | [reference/craft.md](reference/craft.md) | | `extract [target]` | Extract reusable UI components, patterns, and design tokens | [reference/extract.md](reference/extract.md) | -| `critique [target]` | Design-director review with prioritized feedback | [reference/critique.md](reference/critique.md) | -| `audit [target]` | Design and UI-quality implementation report without fixing | [reference/audit.md](reference/audit.md) | -| `polish [target]` | Refine an existing UI to shipping quality | [reference/polish.md](reference/polish.md) | +| `critique [target]` | Design-director review with heuristic scoring | [reference/critique.md](reference/critique.md) | +| `audit [target]` | Technical UI-quality report (a11y, performance, responsive) without fixing | [reference/audit.md](reference/audit.md) | +| `polish [target]` | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `harden [target]` | Make states, errors, a11y, i18n, and edge cases production-ready | [reference/harden.md](reference/harden.md) | | `optimize [target]` | Improve perceived and measured UI performance | [reference/optimize.md](reference/optimize.md) | | `clarify [target]` | Improve labels, microcopy, loading, success, and error text | [reference/clarify.md](reference/clarify.md) | -| `adapt [target]` | Adapt UI to another viewport, device, or input context | [reference/adapt.md](reference/adapt.md) | +| `adapt [target]` | Adapt UI to another viewport, device, or input method | [reference/adapt.md](reference/adapt.md) | | `onboard [target]` | Design first-run, empty, and activation flows | [reference/onboard.md](reference/onboard.md) | | `layout [target]` | Fix spacing, rhythm, hierarchy, and responsive structure | [reference/layout.md](reference/layout.md) | | `typeset [target]` | Improve typography hierarchy, readability, and font strategy | [reference/typeset.md](reference/typeset.md) | @@ -94,6 +118,9 @@ Apply these without fighting the Cheers interaction guardrails. ### Routing rules -1. If the first word of the skill arguments matches a command above, read that reference and follow it. -2. If there is no command, treat the request as general UI design/craft: perform setup, apply the shared design laws, and choose the nearest reference when useful. -3. If implementation changes Cheers templates, use the main `cheers` validation guidance. At minimum, format changed templates with `cargo cheers fmt --rustfmt ` and run targeted checks appropriate to the change. +1. **No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command. +2. **Explicit or clearly implied command:** load its reference and follow it. Ask once if two commands fit. +3. **Workflow or command-selection question:** answer from [routing.md](reference/routing.md#workflow-questions) without executing. +4. **Otherwise:** treat the request as general design work. A new surface or replacement world with no PRODUCT.md goes through `init`, then new-work. A narrow refinement of existing code proceeds on the incumbent implementation and offers `init` afterward rather than blocking on it. +5. `teach` aliases `init`. `craft` is a deprecated alias for ordinary new-work and adds nothing. `shape` owns task discovery, then enters new-work only for visual-world and surface-concept decisions. +6. If implementation changes Cheers templates, use the main `cheers` validation guidance. At minimum, format changed templates with `cargo cheers fmt --rustfmt ` and run targeted checks appropriate to the change. diff --git a/skills/cheers-design/reference/adapt.md b/skills/cheers-design/reference/adapt.md index c9a316c..50cfd99 100644 --- a/skills/cheers-design/reference/adapt.md +++ b/skills/cheers-design/reference/adapt.md @@ -1,58 +1,93 @@ # Adapt -Adapt an existing Cheers design to another viewport, device, input method, or usage context. Adaptation is not scaling pixels; it is rethinking structure for the new context. +Adapt an existing Cheers design to another viewport, device, input method, or usage context. Adaptation is not scaling pixels; it rethinks structure and interaction for the new context. Ask for target devices and usage context when the request and product docs do not name them. -## Discover +## Visitor mode -Identify: +- **Persuade + Experience:** each context may get its own composition when the world earns it. A phone first viewport is a composition of its own, not a squeezed desktop, and still makes the offer intelligible with the primary action in reach. +- **Operate + Read:** the same information architecture, terms, and navigation model in every context. Structure collapses, reflows, and discloses; it never reorganizes into something the user must relearn. -- source context and assumptions: screen size, input, density, connection, user posture -- target context: phone, tablet, desktop, kiosk, print, embedded panel, slow network -- what must remain available -- what can move behind progressive disclosure -- what interaction patterns break: hover-only controls, tiny targets, wide tables, dense sidebars +Refinement preserves: keep the visual world, copy, behavior, and everything outside the adapted contexts. Identity replacement belongs to [new-work.md](new-work.md). -Ask for target devices and usage context if missing. +## Two isolated assessments -## Adaptation strategy +When a subagent tool is available and permitted, run these independently; otherwise run them yourself in this order. + +1. **Adaptation assessment.** Inspect the target in its source context and each target context. Answer each question with rendered or source evidence: + - **Source assumptions:** What was it designed for: screen size, pointer, hover, keyboard, connection, posture, glance or focus? What works well there and must survive? + - **Target context:** Phone, tablet, desktop wide, kiosk, print, email, embedded panel, slow network? Portrait and landscape? Touch, mouse, keyboard, or several at once? + - **Fit:** What will not fit: wide tables, dense sidebars, multi-column forms, long navigation? What can move behind progressive disclosure without hiding core functionality? + - **Input:** What depends on hover, precise pointing, right-click, drag, or keyboard shortcuts? Which targets are too small or too close? + - **Gestures:** Which custom controls (sliders, drag surfaces, carousels, swipe rows, scrollable control strips) exist, and does each have a non-gesture path? + - **Regions:** Do backend-refreshed regions keep one stable home across breakpoints, or does a duplicated mobile tree leave a patch updating only one copy? +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) with `--scope layout`, once at desktop width and once with `--viewport 390x844`, or check by hand when it is unavailable. Also look for fixed widths, horizontal overflow, and `user-scalable=no` the scan may miss. + +Keep scan results out of the first assessment, then synthesize both before editing. A clean scan says nothing about whether a gesture works. + +## Set the adaptation plan + +Before editing, state for each target context: what leads, what moves behind disclosure, what changes interaction model, where the content (not a device list) forces each breakpoint, and which regions reflow, collapse, or stay fixed. State the interaction contract for any control whose input model changes. + +## Apply + +Read [craft-floor.md](craft-floor.md) before editing. Implement through `cheers`. ### Mobile -- Stack content into one clear flow. -- Keep primary actions reachable and large enough. -- Avoid hover-dependent interactions. -- Replace wide tables with summary rows, detail pages, or horizontally scrollable tables only when acceptable. -- Use normal navigation and links for page movement. -- Keep forms short; split only when it reduces cognitive load. +- One clear flow: single column, full-width components, primary content first, secondary content in disclosure. +- Primary actions within thumb reach; the bottom of the screen is easier to reach than the top. +- Navigation collapses to a drawer, disclosure, or a short bar; keep a way back and a sense of place. +- Wide tables become summary rows with detail pages, stacked label-value cards, or a horizontally scrollable table with a visible affordance, chosen by what the user compares. +- Forms stay short; split only when it reduces cognitive load. Body and input text at least 16px, or iOS Safari zooms focused inputs and breaks the layout. ### Tablet -- Use master-detail or two-column patterns when useful. -- Support touch and pointer. -- Let side panels collapse based on orientation or container size. +- Two columns, master-detail, or a collapsible side panel, adapting to orientation or container size. +- Support touch and pointer together; touch-size targets with denser layout than a phone. -### Desktop and wide screens +### Desktop and wide -- Use horizontal space for persistent navigation, side panels, filters, and data comparison. -- Avoid stretching prose or forms across the whole viewport. -- Add keyboard affordances for power workflows where appropriate. +- Use horizontal space for persistent navigation, filters, side panels, and comparison. +- Cap prose and forms with a max width; never stretch to the viewport. +- Add hover detail, keyboard shortcuts, multi-select, and drag where they speed power workflows, each with a non-hover, non-drag path. Desktops have touchscreens too. -### Print or static export +### Print and email -- Hide interactive controls and navigation. -- Expand hidden details that matter. -- Preserve semantic heading order. -- Use print-specific CSS rather than a separate data model when possible. +- **Print:** hide navigation and interactive controls, expand disclosed content that matters, show full URLs, break pages at logical points, keep heading order, and use print CSS rather than a separate data model. +- **Email:** about 600px, single column, inline styles, table layout for client compatibility, large obvious buttons, no hover, deep links back to the app for anything interactive. -## Cheers fit +### Touch and input -- Prefer CSS media/container queries and semantic markup over duplicate component trees. -- If structure truly differs, compose smaller reusable UI pieces. -- Keep conceptual update regions stable across breakpoints. -- Use local affordances for disclosure, not to remove core functionality from a device class. +- Touch targets at least 44x44 CSS px with spacing between them. A small visible mark can sit inside a larger hit area. +- Detect input, not screen size: `(hover: hover)` and `(pointer: coarse)` queries. Nothing essential lives behind hover; touch gets a visible control or an active state instead. +- Every swipe, drag, pinch, or multi-finger gesture has a single-tap alternative: buttons for carousel steps, a menu or visible action for swipe-to-delete, steppers or inputs beside a slider, move buttons beside drag reorder. +- Long-press is never the only way to an action; surface the same action in a visible menu. +- Never disable pinch zoom. Custom pan or zoom surfaces set `touch-action` so the page still scrolls around them. +- Gesture results that change data follow the guardrails: a swipe-delete or drag-reorder shows a pending state and changes the list only after the backend confirms. +- Give touch feedback on press; keep it on the control, not on an image inside it. -Use `cheers` for exact component and patch mechanics. +### Responsive technique + +- Mobile-first: base styles for narrow, `min-width` queries layer complexity. Usually three content-driven breakpoints suffice. +- Container queries for components that appear in contexts of different widths. +- Safe areas: `env(safe-area-inset-*)` with `viewport-fit=cover`, using `max()` for fallbacks on fixed bars. +- Responsive images: `srcset` with width descriptors and accurate `sizes`; `` only for art direction. +- `
` and `` for native progressive disclosure; signals for local open and closed affordances. +- `display: none` still downloads the hidden content's assets; hide sparingly, and prefer not rendering it or `` and `srcset` for imagery. +- Prefer CSS over duplicate component trees. When structure truly differs, compose smaller reusable pieces so each backend-refreshed region still exists once. + +Never hide core functionality on a device class, switch information architecture between contexts, forget landscape, or assume desktop means a powerful device. ## Verify -Test narrow mobile, mobile landscape, tablet/small laptop, desktop wide, keyboard-only, touch, and 200% zoom. For action-driven UI, verify the interaction that changes state. +Inspect in one batched round: narrow phone (320 and 390), phone landscape, tablet, desktop wide, keyboard only, touch, and 200% zoom, on the major engines (Chromium, WebKit/Safari, Firefox) and a throttled connection, plus any named target. Fix everything it shows in one batch and confirm with at most one more round. For action-driven UI, exercise the interaction that changes state in each context. + +Exercise each custom control in scope in the same round: + +- **Primary gesture:** tap it and confirm it responds as designed, then drag it with the target input; the drag must complete, not just start. +- **Scroll across it:** a swipe along the page's scroll axis across the control scrolls the page or container without activating it; a drag that starts on the control along its own axis moves the control, not the page. Neither failure throws an error, so try both. +- **Alternative path:** the non-gesture path reaches the same result. + +Say what produced the evidence: an emulated viewport, synthesized touch through a browser tool, which engine ran it (Chromium is not Safari), or a physical device. Screenshots and resized viewports verify layout, never a gesture. Name what stayed untested and move on; unreachable hardware is a reported gap, not a blocker. + +Format changed templates with `cargo cheers fmt --rustfmt `. When each context feels native, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/animate.md b/skills/cheers-design/reference/animate.md index f70d10c..593cac2 100644 --- a/skills/cheers-design/reference/animate.md +++ b/skills/cheers-design/reference/animate.md @@ -1,82 +1,104 @@ # Animate -Add motion that clarifies state, feedback, hierarchy, or navigation in a Cheers UI. Motion must not hide latency, imply success before confirmation, or require unnecessary JS. +Use motion to explain state, relationship, and hierarchy, or to create one authored moment the surface has earned. Decoration without purpose is animation debt. In Cheers, motion must never hide latency or imply success before the backend confirms it. -## Decide the role of motion +Needs: performance constraints and target devices. Ask only when a material constraint cannot be inferred. -Product surfaces: +## Visitor mode -- 150-250ms for most feedback and state transitions. -- Motion conveys pending, reveal, selection, validation, navigation context, or changed hierarchy. -- No choreographed page-load delays that block task flow. +- **Persuade + Experience:** motion may carry the voice. Prefer one rehearsed focal sequence to repeated section reveals. +- **Operate + Read:** motion serves feedback, state, and continuity. Keep routine transitions fast (150–250ms) and never make users wait through page-load choreography. See [operate.md](operate.md#motion). -Brand surfaces: +Refine inside the established motion language; a new motion identity is part of a new world and belongs to [new-work.md](new-work.md). -- Motion can carry voice: staged reveals, scroll moments, typographic rhythm, image treatment. -- Still preserve accessibility, performance, and readable content. +## Two isolated assessments -Always support `prefers-reduced-motion` with an intentional static or reduced alternative. +When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let scan findings anchor the design assessment. -## Motion hierarchy +1. **Motion assessment.** Inspect the existing motion language, interaction states, backend round trips, target devices, and performance budget. Answer with a file, selector, or computed value. Find only the places where motion would: + - acknowledge an action; + - make a state change or spatial relationship legible; + - preserve continuity through navigation, layout change, or a backend patch; + - direct attention at a meaningful moment; + - embody the selected visual world. + Also find motion that already lies: animations that complete, remove, or reorder before confirmation, and loaders that run without saying what is happening. +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) once against the running page, and check transitions and keyframes in the stylesheets by hand. -Use the smallest tool that achieves the effect: +Do not animate a static area merely because it exists. -1. CSS transitions/keyframes for hover, focus, reveal, and state classes. -2. Native elements/APIs such as `dialog`, `popover`, CSS scroll snapping, and View Transitions when progressive. -3. Cheers/Datastar affordances for local toggles, pending state, and backend-confirmed updates. -4. A static JS helper only when the behavior cannot stay declarative and the experience justifies it. +## Set the motion thesis -Use the main `cheers` skill for exact Datastar syntax and server-pushed behavior. +Before editing, write: -## Patterns to favor +- **Focal moment:** the one sequence or interaction that deserves authorship, if any. It comes from this product and surface; a generic fade-and-rise, hover lift, parallax layer, or scroll reveal is not a thesis. +- **Continuity:** the state, layout, navigation, or patch changes that need explanation. +- **Feedback:** the controls and outcomes that need acknowledgment, split into pending (local, immediate) and confirmed (after the backend responds). +- **Budget:** which effects are expensive and how often they run. -### Reveal +## Choose material by meaning -- Use opacity, transform, clip, or grid-row techniques with short durations. -- Keep the element reachable by keyboard and screen readers. -- Do not hide core content behind hover-only reveals. +Read [craft-floor.md](craft-floor.md) before the first edit; its motion check (one authored moment, ease-out from a visible default, the wider property palette) applies here. -### Pending feedback +- **Continuity and relationship:** view transitions, FLIP-style transforms, deliberate spatial movement. +- **Focus and depth:** bounded blur, filter, backdrop, light, or shadow changes. +- **Reveal and composition:** masks, clip paths, cropping, `grid-template-rows` reveals. +- **Material and energy:** color, gradient position, texture, distortion, shader, or canvas effects when the world and budget support them; anything beyond CSS falls under the JS-is-exceptional guardrail. +- **State and feedback:** the smallest change that makes cause and result unmistakable. -- Animate the pending affordance, not fake success. -- Success or failure appears only from backend-confirmed state. -- For long operations, prefer real progress or staged messages over an endless spinner. +Do not stack techniques for spectacle. Stagger siblings only when a list appears as a list, cap the total delay, and never treat every scrolled section as a staggered list. -### Validation feedback +## Timing and easing -- Transition color, icon, or helper text when a backend-rendered error appears. -- Avoid aggressive shake animations, especially for repeated validation. +| Duration | Typical use | +|---|---| +| 100–150ms | immediate feedback, press, toggle | +| 150–300ms | routine state change, small reveal | +| 300–500ms | layout, overlay, dialog, view transition | +| 500–800ms | a deliberately authored focal entrance | -## Easing and timing - -Use natural deceleration: +Exit faster than entrance. Long feedback feels like latency. Keep easing in the project's tokens; no bounce or elastic curves by reflex: ```css :root { --ease-out-quart: cubic-bezier(.25, 1, .5, 1); - --ease-out-quint: cubic-bezier(.22, 1, .36, 1); --ease-out-expo: cubic-bezier(.16, 1, .3, 1); } ``` -Guidelines: +## Backend-confirmed motion + +- Animate the pending affordance (a disabled control, a progress mark, a status line saying what is happening), never the outcome. No check draws, exit animations, slide-into-list, or reordering until the backend confirms. +- Success and failure motion play only on backend-rendered state. On failure, the pending motion stops and the original state stays visible with the error near the decision point. +- For long operations, prefer real or staged progress over an endless spinner. +- Transition a backend-rendered validation error in with color, icon, or helper text; avoid shake, especially on repeat. +- A patch that changes layout may carry continuity with a view transition; `cheers` owns how patches and signals drive it. + +## Implement with the smallest tool -- 100-150ms: press or toggle acknowledgement. -- 150-250ms: hover, selection, small reveal. -- 250-400ms: larger reveal, drawer/dialog entrance. -- Exits usually shorter than entrances. +1. CSS transitions and keyframes for hover, focus, reveal, state classes, and bounded sequences. +2. Native features: `dialog`, `popover`, scroll snapping, view transitions, scroll-driven animation only when the scroll relationship carries meaning, with a fallback. +3. Datastar signals for local toggles and pending affordances, and backend patches for confirmed updates. +4. A static JS helper (Web Animations API) only when interruption, sequencing, or dynamic values cannot stay declarative. Do not add a JS animation library for an effect CSS expresses cleanly. -Avoid bounce/elastic easing, long feedback animations, and animation that blocks task completion. +Keep content visible in the default state so a failed script or dropped stream never hides the page. Do not animate layout-driving properties (`width`, `height`, `top`, `left`, margins) casually; use transforms, FLIP, or grid techniques. Bound blur, filter, shadow, canvas, and shader work to isolated regions. Apply `will-change` only during a known animation. Measure on target devices rather than assuming transform means fast. -## Performance and accessibility +## Accessibility and control -- Prefer transform and opacity for movement. -- Use blur/filter/mask/shadow only when bounded and verified smooth. -- Avoid layout-property animation unless deliberately measured. -- Do not rely on motion alone to communicate state. -- Preserve keyboard and screen-reader behavior. -- Reduced-motion mode should still look finished. +- Every animation has a `prefers-reduced-motion` path with an intentional alternative: remove or reduce spatial movement while keeping opacity, color, and state changes that carry meaning. Reduced motion means fewer and gentler animations, not disabling all motion. Reduced motion must still feel finished, and feedback confirming an action stays legible. +- Never rely on motion alone to communicate state; keep keyboard and screen-reader behavior intact. +- Respect autoplay and sound preferences. Stop nonessential loops when offscreen or hidden. ## Verify -Check pending state, success/failure timing, reduced motion, keyboard use, mobile/touch, target device smoothness, console errors, and state after backend confirmation. +Inspect in one batched round (desktop and mobile together, plus reduced motion), fix everything it shows in one batch, confirm with at most one more round. Answer each item with rendered or source evidence; a bare "yes" is not verification. + +- The focal motion is specific to the selected world and surface. +- Every supporting animation explains feedback, state, or relationship. +- Pending motion never reads as done; outcome motion plays only after backend confirmation, and failure leaves an honest state. +- Interruption and repeated use behave correctly. +- Desktop, mobile, touch, and keyboard paths remain usable; the console is clean. +- The reduced-motion path reduces movement without erasing meaningful feedback or state changes. +- Expensive effects stay smooth on the target device. +- Removing an animation would lose meaning or authored character, not merely decoration. + +Format changed templates with `cargo cheers fmt --rustfmt `. When motion earns its place, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/audit.md b/skills/cheers-design/reference/audit.md index 4959521..b7ac497 100644 --- a/skills/cheers-design/reference/audit.md +++ b/skills/cheers-design/reference/audit.md @@ -1,70 +1,71 @@ # Audit -Audit a Cheers UI without fixing it. Report actionable issues across UX, visual quality, state trust, accessibility, and implementation fit. Use the main `cheers` skill for exact technical diagnosis when needed. +Run systematic technical quality checks on a Cheers UI and report them without fixing anything; other commands address the findings. This is a code-level audit of what is measurable and verifiable in the implementation, not a design critique: hierarchy, taste, and persona walkthroughs belong to `critique`. Use the main `cheers` skill for exact technical diagnosis. -## Scan dimensions +## Visitor mode -Score each dimension 0-4. +- **Persuade + Experience:** the committed world's expensive effects (large imagery, scroll moments, canvas or WebGL) are legitimate; audit their performance budget, reduced-motion alternative, and fallback, not their existence. +- **Operate + Read:** consistency is measurable: one component and state vocabulary, token use, keyboard paths, tabular numerals in data, a real reading measure on Read surfaces. -### 1. Purpose, flow, and information architecture +## Two isolated assessments -Check for: +Run these yourself in this order, or as independent subagents when the harness can spawn them. Keep scan output out of the first assessment, then synthesize. -- unclear primary action or success condition -- confusing entry path, reading order, or navigation -- too many competing actions or modal-first flows -- hidden dependencies, poor recovery, or unclear next step -- empty/first-run states that fail to orient the user +1. **Technical inspection.** Read the templates, stylesheets, tokens, and any static JS helpers, and inspect the running app at desktop and mobile in one batched round when a browser is available. Score the five dimensions below with file, selector, or computed-value evidence. +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the rendered pages. Verify each finding in context; keep deterministic findings separate from judgment and call out false positives. -Score: 0 = confusing or blocks completion, 4 = obvious, efficient, and confidence-building. +## Dimensions -### 2. Visual craft and design-system fit +Score each 0-4. -Check for: +### 1. Accessibility and semantics -- weak hierarchy, spacing rhythm, alignment, density, or responsive composition -- generic AI tells: gradient text, decorative glass, nested cards, side stripes, equal icon-card grids, hero metrics -- inconsistent component vocabulary or token use -- typography that is flat, illegible, overflowing, or off-register -- brand work without a point of view or product UI that feels unfamiliar without reason +- contrast below 4.5:1 (or 7:1 for AAA) for body and placeholder text, 3:1 for large text; color-only meaning +- missing landmarks, broken heading hierarchy, `div`s instead of buttons or links, unlabeled inputs, missing required indicators, weak error messaging +- custom controls missing a label, role, or state (`aria-expanded`, `aria-pressed`, `aria-selected`) +- keyboard traps, illogical tab order, hover-only controls, missing focus-visible states +- patched or streamed regions that change without a status announcement +- missing or useless alt text; decorative images not hidden +- motion sensitivity: `prefers-reduced-motion` needs an intentional alternative that preserves state change and hierarchy; flag a global `0.01ms` kill that destroys useful feedback, flashing above threshold, and motion that blocks focus, reading, or task completion -Score: 0 = slop or incoherent, 4 = intentional, polished, and system-aligned. +Score: 0 fails WCAG A, 1 major gaps, 2 partial effort, 3 WCAG AA mostly met, 4 AA fully met and approaching AAA. -### 3. Interaction trust and state coverage +### 2. Performance -Check for: +- heavy images without dimensions, lazy loading, or responsive sources; excess font files and weights; layout shift +- layout-property animation, unbounded blur, filter, or shadow effects, visibly dropped frames +- `will-change` applied broadly or left on at rest; it is a targeted hint for a known expensive animation, not a baseline +- layout thrashing in static JS helpers (reading and writing layout in loops); JS shipped where CSS or a native browser feature would do +- an oversized dynamic layer: many tiny patches where one region would do, huge patches that replace stable UI, streams for one-shot work -- optimistic success, removal, completion, or reordering before backend confirmation -- absent loading, pending, error, success, disabled, permission, overflow, or long-data states -- validation/recovery that loses user input or hides next steps -- pending feedback that is invisible, ambiguous, or too celebratory -- local affordances that feel like durable state +Score: 0 severe user-visible cost, 1 major problems, 2 partial optimization, 3 mostly lean, 4 fast and lean. -Score: 0 = untrustworthy or fragile, 4 = complete, honest, and resilient. +### 3. Responsive and touch -### 4. Accessibility and semantics +- fixed widths that break narrow viewports; horizontal scroll; layouts that break at 200% text size; no structural mobile variant +- touch targets under 44x44px +- broken touch interaction: custom sliders, drag surfaces, and scrollable control strips whose primary gesture fails under touch, that swallow page scroll or lose the drag to it, or that stay stuck after an interrupted gesture. Code tells: mouse-only handlers, no `touch-action` on a pointer-event drag surface, drag state that nothing clears on cancel, lost capture, or blur. Exercise the gesture when a browser tool can synthesize touch (a rendered viewport proves layout, not the gesture), then say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested -Check for: +Score: 0 desktop-only, 1 major failures, 2 works with rough edges, 3 minor target or overflow issues, 4 every viewport works and gestures work under touch. -- missing landmarks, heading hierarchy, labels, button/link semantics -- keyboard traps, hover-only controls, missing focus-visible states -- missing status announcements for important dynamic changes -- poor contrast, color-only meaning, touch targets below 44px -- images without useful alt text or decorative images not hidden +### 4. Interaction trust and state coverage -Score: 0 = inaccessible, 4 = WCAG AA-quality with strong semantics. +- optimistic success, removal, completion, or reordering before backend confirmation +- absent loading, pending, error, success, disabled, permission, overflow, or long-data states +- validation that loses user input or hides the next step +- pending feedback that is invisible, ambiguous, or already celebratory +- signals mirroring broad backend state, or local affordances that read as durable state -### 5. Performance and maintainability as experienced by users +Score: 0 untrustworthy or fragile, 4 complete, honest, and resilient. -Check for: +### 5. Implementation integrity -- slow initial load, heavy assets, excessive fonts, or layout shift -- overcomplicated dynamic behavior for a simple task -- janky motion, unbounded blur/filter/shadow, or layout-property animation -- too many tiny updates or huge updates that make state hard to reason about -- duplicated UI patterns that create design-system drift +- hard-coded colors and spacing that bypass tokens; wrong or mixed token types; dark or alternate themes with missing variants, poor contrast, or values that do not update +- repeated implementation shortcuts and design-system drift: the same pattern built several ways, shared components bypassed +- craft-floor Refuse-list elements in the shipped UI, and misleading or decorative content standing in for real content +- structure interchangeable with an unrelated product -Score: 0 = severe user-visible cost, 4 = lean, measured, and maintainable. +Score: 0 systemic drift, 1 major repeated failures, 2 several verified issues, 3 minor isolated issues, 4 coherent and intentional. ## Report format @@ -72,40 +73,58 @@ Score: 0 = severe user-visible cost, 4 = lean, measured, and maintainable. ## Audit Health Score | # | Dimension | Score | Key finding | -|---|---:|---:|---| -| 1 | Purpose, flow, and IA | ?/4 | ... | -| 2 | Visual craft and system fit | ?/4 | ... | -| 3 | Interaction trust and states | ?/4 | ... | -| 4 | Accessibility and semantics | ?/4 | ... | -| 5 | Performance and maintainability | ?/4 | ... | -| **Total** | | **?/20** | **Excellent/Good/Acceptable/Poor/Critical** | +|---|---|---|---| +| 1 | Accessibility and semantics | ?/4 | ... | +| 2 | Performance | ?/4 | ... | +| 3 | Responsive and touch | ?/4 | ... | +| 4 | Interaction trust and states | ?/4 | ... | +| 5 | Implementation integrity | ?/4 | ... | +| **Total** | | **?/20** | **** | + +## Implementation integrity verdict + +Start here. Pass or fail: does the implementation express a coherent, product-specific system? Cite verified evidence and scan findings, with false positives named. ## Trust verdict -Pass/fail for backend-confirmed success, honest pending states, and no optimistic UI. +Pass or fail for backend-confirmed outcomes, honest pending states, and no optimistic UI. -## Top issues +## Executive summary -- [P0/P1/P2/P3] Issue title - - Location: file/component/route if known - - Impact: why it matters - - Recommendation: concrete design fix, plus Cheers implementation area if relevant - - Suggested next command: `cheers-design harden|polish|optimize|craft|animate` +Score and band, issue counts by severity, the top 3-5 issues, next steps. + +## Findings by severity + +- [P0-P3] Issue + - Location: file, component, route + - Category: one of the five dimensions + - Impact: what it costs users + - Standard: the WCAG criterion or standard, if any + - Recommendation: the concrete fix, naming the Cheers implementation area when relevant + - Suggested command: `cheers-design ` + +## Systemic patterns + +Recurring problems that point to a gap rather than a one-off, such as "hard-coded colors in 15 templates" or "touch targets under 44px throughout mobile". ## Positive findings -What should be preserved. +Practices to keep and replicate. + +## Recommended actions -## Recommended order +In priority order: P0 first, then P1, then P2. -1. ... +1. **[P?] `cheers-design `:** what to fix, with context from the findings. ``` +Bands: 18-20 Excellent, 14-17 Good, 10-13 Acceptable, 6-9 Poor, 0-5 Critical. + Severity: -- **P0**: blocks task completion, data trust, or accessibility basics. -- **P1**: major user harm, WCAG AA violation, or backend-confirmed trust violation. -- **P2**: meaningful quality issue with workaround. -- **P3**: polish. +- **P0 blocking:** prevents task completion, breaks data trust, or blocks access. +- **P1 major:** significant difficulty, a WCAG AA violation, or a backend-confirmed trust violation. +- **P2 minor:** an annoyance with a workaround. +- **P3 polish:** no real user impact. -Do not bury the user in P3 noise. Prioritize user harm, accessibility, trust, state coverage, and the biggest visual problems. +Explain every issue's impact, keep recommendations specific, verify before reporting, and do not bury the user in P3 noise. Map findings to the commands that fix them (`harden`, `optimize`, `adapt`, `clarify`, `layout`, `typeset`, `colorize`, `animate`, and so on), and end with `cheers-design polish` when any fixes were recommended. Then tell the user they can run these one at a time, all at once, or in any order, and re-run `cheers-design audit` after fixes to see the score move. diff --git a/skills/cheers-design/reference/bolder.md b/skills/cheers-design/reference/bolder.md index 049815a..06f547f 100644 --- a/skills/cheers-design/reference/bolder.md +++ b/skills/cheers-design/reference/bolder.md @@ -1,68 +1,66 @@ # Bolder -Make a safe or bland Cheers UI more confident without falling into generic AI effects. +Raise a safe or flat part of a Cheers UI to the conviction the rest of the surface already implies, without rebuilding anything the request did not name. The reflex answer, more effects, is the opposite of bold; reject it first. -## Register +Know the target section and what must stay untouched. Ask once if neither the request nor the code makes it clear. -- **Product**: bolder means clearer hierarchy, stronger affordances, better density, and one decisive accent. It rarely means theatrics. -- **Brand**: bolder means stronger point of view. Scale, type, image, color, pacing, and composition can all push harder. +## Which "bolder" -## Assess +An open direction round owns the word first. "Bolder" said while a direction decision in [new-work.md](new-work.md) is on the table is the re-roll register (foreign forms only, at full commitment), not this command. This command refines a surface whose world already shipped. A request for a new world rather than a stronger section is a redesign and routes through new-work.md. -Find why the design feels timid: +## Visitor mode -- flat hierarchy -- medium-sized everything -- weak primary action -- generic centered stack -- low contrast between sections -- timid or absent imagery -- safe neutral palette with no strategy -- no memorable brand moment +- **Persuade + Experience:** bolder means a stronger point of view. Scale, type, imagery, color, pacing, and composition can push harder inside the committed world. +- **Operate + Read:** bolder rarely means theatrics; they undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density, a more legible signature move. The amplification is in clarity, not drama. -Ask about risk tolerance only if the register and product context do not make it clear. +## Scope is sovereign -## Amplify safely +"Everything else stays" is literal. Touch only the named target. Do not restyle its neighbors, migrate the page to a new idea, or add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the system genuinely cannot express the direction, ask before expanding it, naming the exact addition and the job it would do. -### Hierarchy +## Why it reads flat -Pick one focal point and make it unmistakable. Increase contrast between primary, secondary, and tertiary content through size, weight, spacing, and placement before adding effects. +A section usually reads flat for reasons its neighbors already solved. Look at what the rest of the page does that the target does not: display type at full strength, structural devices that carry meaning, the signature motif, density and pacing. A flat section usually opts out of the system's own strongest moves; it often has no clear focal point and a weak primary action. Bring it up to the expressive level its neighbors already reach, in the system's own vocabulary. -### Typography +## State the system -- Product: stronger title/body/label roles, clearer weights, more confident button and tab treatments. -- Brand: larger display type, more distinctive pairings, stronger line breaks, more committed voice. +Before editing, name: -### Color +- the target and its boundary; +- the one decisive move; +- which owned devices (type scale, motif, palette roles, imagery) it reuses at full strength; +- what around it gets quieter so the move reads; +- the interaction contract that must survive unchanged. -- Product: accent only where it carries meaning: primary action, current selection, focus, status. -- Brand: choose Committed, Full palette, or Drenched when the surface earns it. Do not hedge. -- Use OKLCH where the project allows. Avoid pure black/white as the main neutral. +## Apply -### Composition +Read [craft-floor.md](craft-floor.md) first. -Break monotony with asymmetry, varied section rhythm, stronger alignment, or one signature visual motif. Avoid identical card grids. +- **Amplify what the system already owns.** Reuse its motif and type scale at full strength, turned up for this section rather than invented for it. The bolder version looks more like the same brand, not less. +- **Keep content true.** Existing claims are in scope: preserve them unless the user supplies replacements. If real evidence is essential and absent, ask for it. +- **Commit, then clarify.** Half-measures read as noise. Make the one decisive move completely, then quiet everything around it so the move is legible. If every element got louder, the section got flatter. +- **Give it its own rhythm.** The target reads as a peak in the scroll, a shift in density or pace from what surrounds it, not more of the same. +- **Color:** on Operate and Read surfaces accent carries meaning (primary action, selection, focus, status). On Persuade and Experience surfaces take the world's committed strategy to full strength; do not hedge. +- **Motion:** at most one purposeful moment, per [animate.md](animate.md). -### Motion +## The skeleton test -Use purposeful motion only: reveal, feedback, state transition. Brand can have larger choreographed moments; product should stay quick and task-focused. +Strip the copy out of the planned section and study the bare structure. Does it still say what this section is and why it matters through hierarchy and the system's devices alone? If it only works once the words return, the boldness is in the text size, not the design. An image or artifact slot names a job, an anchor and a piece of evidence, not a cue for a decorative photo; fill it with what the subject actually has. ## Cheers fit -- Do not add client-side state just to make the UI feel lively. -- Do not show success or completed state before backend confirmation. -- Let the bolder treatment apply to confirmed states and honest pending states. -- Use `cheers` for exact implementation choices. +- Boldness lands on rendered, backend-confirmed states and honest pending states. Never make success louder by showing it before the backend confirms. +- Do not add signals or client state to make the UI feel lively. +- Forms, actions, and update regions the section carried keep working the same way. +- Use `cheers` for implementation; format changed templates with `cargo cheers fmt --rustfmt `. -## Never +## Verify -- Gradient text. -- Decorative glassmorphism. -- Cyan/purple glow as a default bold move. -- Side-stripe card accents. -- Making every element loud. -- Sacrificing readability, contrast, keyboard use, or performance. +Inspect desktop and mobile in one batched round, fix everything in one batch, confirm with at most one more round. Answer each item with rendered or source evidence, not a bare yes: -## Verify +- Everything outside the target is unchanged. +- No new color, font, or system primitive appeared unasked. +- The skeleton still says what the section is. +- The section is unmistakably the same brand, only more sure of itself. +- Contrast, keyboard paths, reduced motion, and state trust still hold. -Would a user trust the bolder product UI more, not less? Would the brand surface be remembered? Does it still pass accessibility, reduced motion, and state trust? +When the target holds its own without pulling the page apart, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/brand.md b/skills/cheers-design/reference/brand.md deleted file mode 100644 index 822b880..0000000 --- a/skills/cheers-design/reference/brand.md +++ /dev/null @@ -1,75 +0,0 @@ -# Brand register - -Use this when design is the product: landing pages, marketing surfaces, campaign pages, portfolios, public storytelling, long-form content, and brand moments where the visitor's impression is the deliverable. - -## Brand slop test - -If someone could look at the page and say "AI made that" without hesitation, it failed. Brand surfaces need a point of view, a specific audience, and a willingness to risk strangeness when the brief calls for it. - -Before committing, name the aesthetic lane. A technical product launch, a luxury hotel, a music campaign, and a research lab can all be brand surfaces, but they should not share the same beige editorial template. - -Run the inverse test: describe the concept in one sentence the way a competitor would. If the sentence fits the average page in the category, restart. - -## Typography - -### Font selection - -1. Write three concrete brand-voice words. Use physical qualities such as warm, mechanical, ceremonial, clinical, restless, tactile. Avoid empty words like modern or clean. -2. Name the fonts you would reach for by reflex, then challenge them. Training-data defaults create monoculture. -3. Choose type as if it were a physical object: museum caption, terminal manual, fabric label, concert poster, receipt, field guide, laboratory tag. -4. Cross-check the category reflex. Technical does not automatically mean mono. Elegant does not automatically mean serif. - -### Pairing and scale - -- Use two families only when voice needs it. A single well-chosen family with strong size and weight contrast can be more distinctive. -- Use fluid display sizing and stronger scale contrast when the surface earns it. -- Light text on dark backgrounds needs more line-height and often stronger weight. -- Avoid repeated tiny uppercase labels unless they are a deliberate brand grammar. - -## Color - -Brand surfaces can use **Committed**, **Full palette**, and **Drenched** strategies. Use them when they serve the story. - -- Name a real reference before picking a palette. -- Palette is voice. A calm brand and a restless brand should not share palette mechanics. -- Do not hedge when the strategy is Committed or Drenched. -- If a cultural-symbol palette is obvious, reach past it. Let typography, imagery, and copy carry the cultural signal. - -## Layout - -- Centered stacks are a default, not a concept. -- Use asymmetry, strict grids, visible structure, oversized type, generous pacing, or single-purpose sections when they match the brand. -- Vary rhythm across sections. Brand pages can breathe, compress, pause, and accelerate. -- Cards are valid only when they are the right affordance or the chosen visual grammar. - -## Imagery - -Image-led briefs need imagery. Restaurants, hotels, travel, fashion, photography, products, communities, and places usually cannot be solved with colored rectangles and cards. - -- Use real project assets when available. -- One decisive image beats five mediocre ones. -- Alt text is part of voice and context. -- Imagery can also be product screenshots, data visualization, generated SVG, canvas, WebGL, or illustration when that is the actual visual world. - -## Motion - -- Brand can use larger reveals, scroll moments, typographic choreography, and atmospheric effects. -- Motion still needs purpose, performance, and reduced-motion alternatives. -- One memorable motion idea beats scattered micro-interactions. - -## Brand bans - -- Monospace as lazy shorthand for technical. -- Large rounded icons above every heading as a template move. -- Timid palettes and average layouts when the brief needs identity. -- Zero imagery when the subject implies imagery. -- Editorial magazine aesthetics by default. -- Repeating the same kicker, card, and metric grammar across every section. - -## Brand permissions - -- Typographic risk. -- Unexpected color strategies. -- Single-purpose folds and deliberate pacing. -- Art direction per section when the narrative demands it. -- A signature visual motif that would be too loud for product UI. diff --git a/skills/cheers-design/reference/clarify.md b/skills/cheers-design/reference/clarify.md index 959e461..1669625 100644 --- a/skills/cheers-design/reference/clarify.md +++ b/skills/cheers-design/reference/clarify.md @@ -1,68 +1,99 @@ # Clarify -Improve UX copy, labels, help text, errors, and status messages in a Cheers UI. Clear copy reduces mistakes and makes backend-confirmed state understandable. +Rewrite unclear interface text in a Cheers UI so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice. Clear copy reduces mistakes and makes backend-confirmed state understandable. -## Assess +## Visitor mode -Find copy that is: +- **Persuade + Experience:** copy carries the voice. Headlines may be bold and specific, but the offer, the proof, and the action stay plain enough to act on within seconds. +- **Operate + Read:** plain language and stable terms first. Labels, statuses, and errors are scanned under pressure; cleverness costs time. -- vague: "Submit", "Error", "Invalid input" -- repetitive: heading and intro saying the same thing -- jargon-heavy or based on internal model names -- passive or evasive during errors -- too clever for high-stress moments -- missing a next step -- inconsistent with terms used elsewhere +Refinement preserves: keep voice, terms the audience genuinely knows, and every factual claim. Ask before changing factual claims, legal meaning, or a term that may be domain-specific, and never add claims. -Ask for audience technical level and user mental state only when the code/product docs do not answer it. +## Two isolated assessments -## Copy rules +When a subagent tool is available and permitted, run these independently; otherwise run them yourself in this order. -- Button text should name the action: "Save settings", "Invite member", "Retry upload". -- Loading text is honest: "Saving...", "Checking availability...". It must not imply success. -- Success text appears only from backend-confirmed state. -- Error text explains what happened and what to do next. -- Validation messages come from backend validation or the source of truth for the action, then appear near the field. -- Empty states explain what will appear, why it matters, and the first useful action. -- Avoid em dashes, filler adjectives, and generic AI loading jokes. +1. **Language assessment.** Read the whole interaction path in context, not isolated strings. Infer audience knowledge and emotional state from PRODUCT.md and the surrounding UI; ask only when they do not answer it. Find: + - vague labels and outcomes: "Submit", "Error", "Invalid input", "Done"; + - internal jargon, model names, or assumed knowledge; + - missing consequences, recovery, or timing; + - inconsistent nouns, verbs, and capitalization for the same concept; + - redundancy: a heading and intro saying the same thing, helper text restating the control; + - pending or success copy that claims more than the backend has confirmed; + - tone that ignores stress, risk, success, or urgency; + - text that breaks at realistic widths or in translation. +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) or check by hand: kickers and eyebrows, em dashes in product copy, icon-only controls without accessible names, placeholder-only labels, link text that fails out of context. -## Rewrite common areas +Keep scan results out of the first assessment, then synthesize both before editing. + +## Set the message hierarchy + +For each state, decide before rewriting: + +1. the one fact the user needs now; +2. the action available next; +3. supporting context that changes the decision; +4. the tone for this moment. + +Say each idea once. If the heading already explains the state, the introduction adds new information or disappears. When inconsistency spans the product, keep a short terminology glossary and apply it everywhere; do not vary words for literary effect in an interface. + +## Rewrite by function + +### Actions and navigation + +- Use a specific verb and object when the outcome is not already obvious: "Save settings", "Invite member", "Retry upload". Describe the outcome, not the gesture. +- Use the same noun and verb for the same concept across navigation, headings, forms, and buttons. +- Destructive actions name the object and consequence: "Delete deployment `green-42`? This removes its logs from the dashboard." The confirm button repeats the action ("Delete deployment"), never `Yes`, `OK`, or `Submit`. +- Prefer backend-modeled undo over confirmation when recovery is safe. ### Forms -Use visible labels, not placeholder-only labels. Hints should answer why or format: +- Persistent visible labels; placeholders are examples, not labels. Bad: "DOB". Good: "Date of birth" with the hint "Use YYYY-MM-DD." +- Format and eligibility requirements appear before submission. Explain why information is requested only when it is not obvious. Treat required and optional consistently. +- Validation messages come from the backend, the source of truth for the action, and appear at the field: what needs attention and how to fix it, without blame. -- Bad: "DOB" -- Good: "Date of birth" plus hint "Use YYYY-MM-DD." +When changing fields, use `cheers` to keep labels, hints, and errors wired to the form. -When changing fields, use the main `cheers` skill to keep form wiring aligned. +### Errors and permissions -### Errors +An actionable error answers what failed, why when known and useful, and how to recover or what alternative remains. -- Bad: "Forbidden" -- Good: "You do not have permission to edit this project. Ask an owner for access." +- Bad: "Forbidden". Good: "You do not have permission to edit this project. Ask an owner for access." +- Never lead with internal codes or raw errors. Never promise a cause or resolution the system cannot know. +- Privacy, payment, deletion, access loss, and blocked work get serious copy; warmth is welcome, jokes are not. +- Newly appearing important errors are announced through live status, not only shown. -Place field-level errors near inputs and connect them semantically where practical. Use alert/live treatment for newly appearing important errors. +### Pending, empty, and success -### Loading and pending +- Pending text names the real operation: "Saving...", "Checking availability...". Set an honest expectation when the wait is meaningful; show determinate progress only when the backend provides it. +- Bad: "Done" before the response arrives. Good: "Saving..." while pending, then "Saved" or the error, only after backend confirmation. +- Empty states distinguish first use, no results, active filters, permissions, and failure; each explains the state and offers the next useful action. +- Success confirms the completed outcome and mentions the next consequence only when it changes what the user should do. Routine success stays brief. -- Bad: "Done" before the response arrives. -- Good: "Saving..." while pending, then "Saved" or the error only after backend confirmation. +### Help text -### Destructive actions +Helper text answers an implicit question instead of restating the control. Put uncommon detail behind progressive disclosure. Link text makes sense out of context; icon-only controls get accessible names that match their visible meaning. -Name the object and consequence: +## Voice, accessibility, and localization -- "Delete deployment `green-42`? This removes its logs from the dashboard." +Voice stays consistent; tone adapts to the moment. Use the product's own language, with no filler adjectives, em dashes, or generic loading jokes. -Undo should be backend-modeled or otherwise truthful, not optimistic removal with a fragile rollback. +- Write complete translatable messages, never concatenated fragments; keep variables and numbers structured so translators can reorder them, and handle plurals properly. +- Allow for 30 to 40% expansion instead of abbreviating early. +- Alt text conveys the image's information; decorative images get empty alt. +- Screen-reader names match visible labels and outcomes. +- Punctuation, color, or an icon never carries the message alone. ## Verify -- A first-time user knows what to do next. -- Error copy is specific, recoverable, and blame-free. -- Terms match across navigation, headings, forms, and actions. -- Copy survives longer translations and small screens. -- All success messages are backend-confirmed. +Read the flow in context, desktop and mobile in one batched round, and confirm with evidence: + +- a first-time user knows what to do next without hidden product knowledge; +- errors, empty states, and decision points are actionable, specific, and blame-free; +- claims are factually unchanged and terms match everywhere; +- copy scans at target widths and 200% zoom and survives long names, translation, plurals, and dynamic values; +- accessible names and announced state changes match the visible copy; +- tone is appropriate to the consequence and emotional context; +- every success message renders only from backend-confirmed state. -Finish with `polish` if visual hierarchy or spacing still needs refinement. +Fix what the round shows in one batch and confirm with at most one more round. The final copy is as short as it can be without losing meaning or recovery. Format changed templates with `cargo cheers fmt --rustfmt `. When the language reads cleanly, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/colorize.md b/skills/cheers-design/reference/colorize.md index df82d48..fcf8314 100644 --- a/skills/cheers-design/reference/colorize.md +++ b/skills/cheers-design/reference/colorize.md @@ -1,57 +1,90 @@ # Colorize -Introduce color strategically in a Cheers UI. More color is not better. Color must carry meaning, hierarchy, or brand voice. +Introduce color as hierarchy, meaning, and atmosphere. Preserve confirmed brand and semantic conventions; do not replace a visual world under the guise of colorizing it. -## Register +Needs: the existing brand colors (DESIGN.md, tokens, assets). Ask only when a binding brand decision cannot be inferred. -- **Product**: semantic-first, usually Restrained. Accent means primary action, selected state, focus, or status. -- **Brand**: color can be the voice. Committed, Full palette, and Drenched are valid when intentional. +## Visitor mode -## Assess +- **Persuade + Experience:** color may carry the voice and own large regions when the selected world calls for it. Committed, Full palette, and Drenched are available. +- **Operate + Read:** color primarily encodes action, selection, status, wayfinding, and reading hierarchy. Rarity gives an accent force, but color still does real jobs in the shell. See [operate.md](operate.md#color). -Identify: +If the task actually needs a new identity, route through [new-work.md](new-work.md) and DESIGN.md. -- existing brand colors or CSS tokens -- current neutral temperature -- semantic states needed: success, error, warning, info, selected, disabled, loading -- places where color would improve wayfinding or hierarchy -- contrast failures or gray-on-color problems -- category-reflex palettes to avoid +## Two isolated assessments -## Plan +When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let scan findings anchor the design assessment. -Choose a strategy before values: +1. **Color assessment.** Read DESIGN.md, tokens, stylesheets, assets, current themes, and representative states. Answer each with a file, selector, or computed value: + - Which colors are confirmed brand commitments? + - What are the current surface, text, action, focus, and semantic roles, and where are they defined? + - Where does grayscale obscure hierarchy or state? + - Where does contrast fail, or does color alone carry meaning? + - What light/dark, data-visualization, or category-reflex palette constraints apply? + - Does the request ask for more color, or for a new identity? +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) once against the running page for contrast and palette findings; also check colors set in `html!` templates by hand. -1. Restrained: tinted neutrals plus one accent. -2. Committed: one saturated color owns much of the surface. -3. Full palette: 3-4 named roles with strict use. -4. Drenched: color is the environment. +Synthesize both before editing. -Use OKLCH when possible and reduce chroma near very light or very dark values. +## Choose a strategy -## Apply +Before editing, name the color strategy (Restrained, Committed, Full palette, or Drenched, as in [new-work.md](new-work.md#4-commit-the-world)), the emotional temperature, the dominant relationship, the contrast range, and the dosage. Follow the brief and the selected world, not a fixed percentage rule. -### Product +Build roles, not a bag of swatches: -- Primary button and active nav use the accent. -- Error/warning/success/info use consistent semantic colors. -- Focus rings are visible and color-safe. -- Loading indicators use a pending affordance color without implying success. -- Charts and badges use palettes that are distinguishable beyond color alone. +- canvas and elevated surfaces; +- primary and secondary text; +- action, focus, and selection; +- borders and separators; +- success, warning, error, info, and pending; +- data categories or scales when needed. -### Brand +Use the project's existing color space. For a new web palette, prefer OKLCH so lightness and chroma move predictably. Choose hue from product meaning and the visual direction, never from the category's default association. -- Let the chosen color strategy affect composition, not just buttons. -- Use image/illustration/color together where the brief calls for a visual world. -- Avoid default tech gradients and decorative glow. +## Apply at system scale -## Cheers fit +Read [craft-floor.md](craft-floor.md) before the first edit; its contrast check and surface refusals (gradient text, decorative glass, side stripes) apply here and are not repeated. -- Put palette values in CSS variables or the existing token system. -- Keep backend-confirmed states using the same semantic classes/tokens. -- Do not use color-only status. Add text, icon, shape, or position. -- Do not use side-stripe card accents. Use full hairline borders, tints, leading icons, or labels. +- Let the strongest color own a deliberate region or role instead of scattering tiny accents. +- Keep the primary action easy to find; do not spend its color on decoration. +- Tint neutrals toward the world's hue for cohesion. A true neutral is valid when it serves the world, never as an unexamined default. +- On colored surfaces, derive secondary text from the foreground or surface hue, never a washed-out generic gray. +- Keep semantic meanings consistent, while respecting domain conventions instead of assuming fixed hues. +- For data, vary lightness, chroma, shape, label, or pattern so color is never the only code. +- In dark mode, design surface elevation and contrast explicitly; never invert the light theme mechanically. +- Define primitives and semantic tokens as CSS custom properties in the project's token file. Themes remap semantic roles; templates reference roles only: + +```css +:root { + --ink-900: oklch(22% 0.02 250); + --sea-600: oklch(52% 0.16 235); + --color-text: var(--ink-900); + --color-action: var(--sea-600); +} +``` + +Decoration without a relationship to hierarchy, state, content, or the visual world is not a color strategy. + +### Contrast and perception + +Beyond the craft floor's text ratios, controls, icons, and focus indicators need 3:1 against their surroundings. Check computed pairs in interactive states, overlays, text on images, disabled content, and both themes; simulate common vision deficiencies. When deriving OKLCH ramps, reduce chroma near white and black. Prefer explicit colors over chains of translucent overlays whose contrast depends on context. + +### Cheers fit + +- The pending color is its own role and never borrows success. Success color appears only on backend-confirmed state; error color only on a real failure (backend or validation). +- Backend-rendered states use the same semantic tokens and classes as the component's normal state. +- Status never relies on color alone: pair it with text, an icon, shape, or position. +- Use `cheers` for rendering mechanics. Format changed templates with `cargo cheers fmt --rustfmt `. ## Verify -Check WCAG contrast, color blindness, dark/light variants if present, reduced motion, and all state changes. Color should clarify what changed, not merely decorate it. +Inspect in one batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, then rerun the scan once. Answer each item with rendered or source evidence; a bare "yes" is not verification. + +- Every color has a stable role or a world-specific atmospheric purpose. +- Attention lands on the intended action, content, or state. +- The palette holds across quiet, dense, interactive, pending, error, and empty states. +- Light and dark themes are each composed, not mechanically inverted. +- Contrast and non-color cues pass in every relevant state. +- The result is recognizably this product, not a generic colorful treatment. + +When the palette earns its place, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/craft-floor.md b/skills/cheers-design/reference/craft-floor.md new file mode 100644 index 0000000..13ebb8f --- /dev/null +++ b/skills/cheers-design/reference/craft-floor.md @@ -0,0 +1,49 @@ +# Craft floor + +Load this after the direction is settled, and build without announcing the checklist. A pinned brief or the committed visual world overrides anything here; your own habit does not. + +## Verify + +Each of these is a check on the built result, not an intention. Run them together in the batched inspection rounds, not as separate screenshot trips; the checks share one render. + +- **Contrast:** body and placeholder text ≥4.5:1, large text ≥3:1. On colored surfaces tint secondary text from that hue or the foreground; never gray. +- **Depth:** shadows carry an offset and a soft blur. A zero-offset colored halo is decoration. Declare elevation once, border or shadow: a 1px border under a wide soft shadow is the ghost card. Card radii stay at 12–16px; pills are for small controls. +- **Spacing:** tight groups, generous separation, more space above a heading than below it. Read the computed values. +- **Type:** body measure 65–75ch, display max 6rem, tracking floor -0.04em (-0.02 to -0.03em usually reads better), balanced headings, obvious scale and weight steps. Run the real copy at every breakpoint and fix what overflows. +- **Motion:** one authored moment, not scattered effects and not one identical entrance on every section. Exponential ease-out from an already-visible default. Reach past transform and opacity: blur, backdrop-filter, clip-path, mask, and shadow belong to the palette when they stay smooth. +- **States:** hover, focus-visible, active, disabled, loading, pending, error, empty, success. Pending never reads as done; success appears only after the backend confirms it. Plus real content, working controls, responsive composition, keyboard focus, touch targets, and status changes announced to assistive technology. +- **Browser surfaces:** the parts you did not draw still carry the design. Text selection, the caret, custom scrollbars, focus rings, underline offset, and the numerals in tabular data all ship with browser defaults that belong to no design system. Theme them from the palette. This is the cheapest signal that a page was built rather than assembled, and the one models skip most reliably. +- **Copy:** the product's own language. Controls name their action; errors name the problem and the recovery. +- **Coverage:** every brief requirement present and findable within seconds. + +## Refuse + +These are the category's defaults, not bans: the brief's own words can earn any of them. Reaching for one when the axis is free means you were not deciding; recognizing that means rewriting the element, not softening it. + +Page scaffolds: + +- Same-size cards of icon plus heading plus text as the page structure. Cards are the lazy container; nested cards are always wrong. +- The hero-metric template: big number, small label, supporting stats, accent. +- A kicker or eyebrow above a heading. This one is a ban, not a default: no brief earns it back. The heading carries its own weight; delete the label and let the heading speak. +- Section numbers (01 / 02 / 03) unless the sequence itself carries information the reader needs. +- A modal for a task that needs neither interruption nor protected focus. + +Surface habits: + +- Gradient text. Emphasis comes from weight or size. +- Glass and blur as decoration rather than as a specific effect. +- A colored `border-left` or `border-right` above 1px on cards, list items, callouts, or alerts. +- Hard offset shadows (`box-shadow: 4px 4px 0`) outside a world that is actually neobrutalist. The zero-blur block shadow is a costume, not a depth system. +- Sparklines, progress rings, and soft-shadowed rounded rectangles standing in for content. +- Monospace as a costume for "technical" rather than for code, data, or measurement. +- A system display face (Impact, Arial Black, the platform sans) as the display voice of an own-world page. Source and self-host a face whose character matches the approved lettering; the closest installed font is a failure, not a fallback. +- Unicode glyphs or emoji standing in for an icon system. Icons are drawn, from a real library or authored SVG, in one consistent stroke and weight. +- Geometric masks standing in for organic contours. A circle, polygon, or radial-gradient cutout approximating a photographic subject's edge reads worse than omitting it. Use a real alpha matte or a cut-out asset. +- Sketch-style SVG scenes and `feTurbulence` grain imitating illustration. Real illustration or none. This bans SVG imitating pictures, never SVG doing geometry: crisp vector shapes, diagrams, animated linework, and shader-driven effects stay first-class. A shaded, perspectived, or figure-bearing illustration is a picture even in line-art style; geometry means shapes you can specify exactly. +- Stripe and grid-overlay backgrounds with no canvas, map, blueprint, or measuring tool under them. Backgrounds are surfaces, textured only from the subject's world. +- Animating an image on hover, directly or through its parent. It is not an action target; give the container the feedback. +- Light or dark picked by category. Pick it from the use scene: who, where, under what ambient light. + +Claims and configuration come from supplied truth; label illustrative values honestly. Naming a concept and then ironizing it is not a claim. + +The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit. diff --git a/skills/cheers-design/reference/craft.md b/skills/cheers-design/reference/craft.md index 526b670..9964d78 100644 --- a/skills/cheers-design/reference/craft.md +++ b/skills/cheers-design/reference/craft.md @@ -1,102 +1,5 @@ -# Craft +# Craft (deprecated alias) -Build a confirmed design brief into production-quality Cheers UI, then inspect and refine it. Craft is where design decisions become code, but the exact Cheers mechanics come from the main `cheers` skill. +`craft` is a deprecated alias for an ordinary request to make new visual work. It adds no setup, interview, checkpoint, or quality behavior. Apply SKILL.md's normal routing: create missing PRODUCT.md through [init.md](init.md), then follow [new-work.md](new-work.md) for visual authority, world and surface decisions, implementation, and finish. -## Gate - -Do not start code edits until one is true: - -- The user confirmed a `shape` brief for this task. -- The user supplied an already-confirmed brief. -- The user explicitly asked to skip shaping and proceed. - -Before editing, load `cheers` for implementation rules, the matching register reference, and any relevant design references such as `layout`, `typeset`, `colorize`, `harden`, `animate`, or `polish`. - -Briefly state: confirmed brief status, register, primary action, interaction contract, and the fact that success remains backend-confirmed. - -## Visual direction and assets capability gate - -If the harness provides native image generation, screenshot comparison, or sub-agent asset production, use those capabilities before implementation when the brief is visually open-ended, image-led, brand-heavy, or production-ready: - -1. Ask 2-3 targeted visual direction questions if palette, atmosphere, or references are still unresolved. -2. Produce or request 1-3 distinct visual direction probes or mocks. -3. Stop for approval or explicit delegation before coding. -4. Inventory the approved direction's major ingredients: hero silhouette, imagery/media, typography, palette, section structure, signature motifs, motion cues, and what should remain semantic HTML/CSS/SVG rather than raster. -5. Use a scoped sub-agent for asset production only when the harness supports sub-agents and the user allows it. - -This flow is **not Codex-exclusive**; upstream names one file `codex.md` because Codex exposes native image generation there. In Pi, only run the generated-mock or asset-subagent steps when those capabilities are actually available. If they are unavailable, state that the visual-generation step is skipped and implement directly from the confirmed brief. - -## Build passes - -### 1. Re-anchor the design - -Extract from the brief: - -- primary user action and success condition -- visual lane, theme scene, color strategy, typography tone, density, imagery needs -- required states and edge cases -- responsive expectations -- existing design-system components or tokens to preserve -- anti-goals and generic AI tells to avoid - -If these are materially unclear, stop and ask. - -### 2. Design the structure before details - -Sketch the code plan in design terms: - -- page landmarks and heading hierarchy -- content groups and reading order -- primary, secondary, and tertiary actions -- form, table, list, detail, empty, and error patterns -- patchable or refreshable regions as conceptual boundaries -- mobile structure, not just squeezed desktop - -Do not begin by styling a pile of divs. Build semantic shape first. - -### 3. Implement through the Cheers skill - -Use `cheers` for exact choices around `Render`, generated helpers, Datastar attributes, actions, patches, streams, tests, and formatting. - -From this skill, keep the implementation aligned with design intent: - -- interaction remains honest and backend-confirmed -- pending feedback is visible and does not imply success -- local client affordances stay local -- state and errors render near the user decision point -- components are extracted when they clarify repeated UI, not to abstract prematurely -- CSS follows project conventions and token vocabulary - -### 4. Finish visual, content, and responsive quality - -- Replace placeholder copy with real, task-specific content. -- Ensure every relevant state has layout, copy, and visual treatment. -- Tune spacing, alignment, density, type hierarchy, and color roles. -- Check hover, focus-visible, active, disabled, pending, error, and success states. -- Add purposeful motion only when it clarifies feedback, hierarchy, reveal, or transition. -- Preserve accessibility: labels, landmarks, status announcements, keyboard path, touch targets, contrast. - -### 5. Inspect and iterate - -When practical, inspect the rendered UI at mobile, tablet/small laptop, and desktop. Compare against: - -- confirmed brief -- register reference -- design system and neighboring surfaces -- state coverage -- anti-pattern list -- performance and motion constraints - -Fix material defects. Do not invent fake defects just to show iteration. - -## Present - -Summarize: - -- files changed -- design decisions that connect to the brief -- interaction contract used -- states covered -- viewports or rendered checks performed -- formatting/tests/checks run through `cheers` guidance -- remaining limitations or follow-up risks +Do not tell users they need to invoke `craft`. Natural requests such as "build this feature", "make a landing page", or "redesign this screen" use the same flow. diff --git a/skills/cheers-design/reference/critique.md b/skills/cheers-design/reference/critique.md index 808ce6b..374a1a0 100644 --- a/skills/cheers-design/reference/critique.md +++ b/skills/cheers-design/reference/critique.md @@ -1,159 +1,207 @@ # Critique -Run a design-director review of a Cheers UI and produce prioritized feedback. Critique may inspect code and rendered output, but does not fix issues. +Run a design-director review of a Cheers UI: resolve one stable target, run two isolated assessments, synthesize one report, persist a snapshot, and ask what to improve next. Critique inspects code and rendered output but fixes nothing. -Critique is also the source of a reusable backlog: persist the final report under `.cheers-design/critique/` so later `polish` runs can consume prior P0/P1 findings without copy-paste. +The chat report is the deliverable. The snapshot under `.cheers-design/critique/` is an archive of the run that later `polish` runs read as a backlog. -## Inputs +## Setup -Clarify the surface goal if it is not obvious. A critique without knowing the intended primary action is mostly taste. +1. **Resolve the target** to a concrete file path or URL. Prefer a source path over a dev-server URL when both identify the same surface; ports drift, paths do not. + - "the homepage" -> `src/pages/home.rs` or the module that renders it + - "the settings modal" -> the primary component file + - "this page" -> the current URL only if no source path is identifiable +2. **Know the goal.** Read PRODUCT.md, DESIGN.md, and the surface brief (`.cheers-design/surfaces/.md`) when present; its direction contract is what the render must keep. If the primary action is still unclear, ask: a critique without it is mostly taste. +3. **Compute the slug:** -Resolve the target to a stable file path or URL before reviewing. Prefer a source path over a dev-server URL when both identify the same surface; ports drift, paths do not. + ```bash + node /scripts/critique-storage.mjs slug "" + ``` -Examples: + Never hand-write a slug. If it exits non-zero (the target has no stable slug: empty input or the project root), continue the critique and skip persistence and trend. +4. **Read `.cheers-design/critique/ignore.md`** if it exists and drop matching findings silently. It is the only prior-run input critique consumes; do not read earlier snapshots before assessing. -- "the homepage" -> `src/pages/home.rs`, `templates/home.html`, or equivalent source -- "the settings modal" -> the primary component file -- "this page" -> current URL only if no source path is identifiable +## Visitor mode -## Persistence setup +Take the mode from the surface brief, or choose it from the requested surface per SKILL.md. -Use the helper script from this skill directory: `scripts/critique-storage.mjs`. Resolve it against the skill directory before running commands. +- **Persuade + Experience:** judge commitment and specificity. Does the first viewport make the offer intelligible, the action findable, and the product's proof visible within seconds (Persuade), or let the work lead (Experience)? A clean but category-default page is a finding, not a pass. Heuristics 7 and 10 may score `n/a`. +- **Operate + Read:** judge earned familiarity per [operate.md](operate.md): can a category-fluent user trust every control, density, and term without pausing? Task speed, state vocabulary, and consistency outrank expression; on Read, measure, wayfinding, and the reading column come first. -1. Compute the slug: +## Two isolated assessments - ```bash - node /scripts/critique-storage.mjs slug "" - ``` +When a subagent tool is exposed, run A and B as two isolated subagents in parallel, each with a self-contained prompt: cwd, target, dev-server URL, the reference paths it needs, product context, and the output contract below. They must not see each other's output, and no findings reach the user before synthesis. This is mandatory: running them inline is a degraded run and is not permitted for speed or convenience. Subagents are unavailable only when no subagent tool is exposed, or when the harness asks permission to spawn and the user declines; name that reason. Without subagents, finish and record Assessment A before starting B, and make the report's first line `Degraded: single-context ()`. A silent degraded run is a failed run. + +When browser automation is available, a viewable target requires inspecting the running app at desktop (1440 wide) and mobile (390 wide) in one batched round; each assessment opens its own fresh tab. Prefer the harness's native browser or screenshot tool; hand-write a Playwright or Puppeteer script only when no native tool is exposed. Without a browser, review source and state the limitation. Any server started only for the critique runs in the background and is stopped before reporting unless the user asks to keep it. + +### Assessment A: design review + +Think like a design director. Answer with rendered or source evidence: + +- **Design specificity:** is the composition, interaction, and visual language grounded in this product, or could an unrelated product use it unchanged? Judge this before any scan output exists. +- **Holistic design:** hierarchy, information architecture, discoverability, composition, typography, color, copy, accessibility, responsive structure, states, and edge cases. Hold the render against [craft-floor.md](craft-floor.md)'s Refuse list and Verify checks. +- **Interaction trust:** success, removal, completion, and reordering appear only after backend confirmation; pending states say what is happening without implying it is done; signals stay local affordances and never pose as durable state; the dynamic layer is the smallest one that works. +- **Cognitive load:** the checklist below; name every failed item and every decision point with more than four visible options. +- **Emotional journey:** the peak and the end, emotional valleys, and reassurance at high-stakes moments. +- **Heuristics:** score all ten, marking `n/a` only where the mode rule allows. +- **Personas:** walk two or three through the primary action. + +Return: specificity verdict, interaction trust verdict, heuristic scores, cognitive load, emotional journey, 2-3 strengths, 3-5 priority issues, persona red flags, minor observations, and provocative questions. - Keep the slug. If it exits non-zero because the target is vague or root-level, continue the critique and skip persistence. +### Assessment B: mechanical scan -2. Read `.cheers-design/critique/ignore.md` if it exists. Drop matching findings silently; it is the user's explicit ignore list for repeated critique noise. +Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) against the rendered page, once at desktop and once with `--viewport 390x844`; for a multi-view target, scan three to five representative pages. When the tool is unavailable, run the manual check SKILL.md describes and say so. Never block on it. -## Assessment passes +Return: finding counts, rule names, locations, suspected false positives, and any skipped step with its concrete reason. The parent reuses these findings; rerun only when B failed, was truncated, or omitted counts, rules, or locations. -When practical, run two independent passes before synthesizing: +## Heuristics -1. **Design pass**: hierarchy, information architecture, visual quality, copy, state coverage, accessibility, responsive behavior, emotional fit. -2. **Interaction fit pass**: whether dynamic behavior stays backend-confirmed, pending states are honest, and local affordances do not pretend to be durable app state. +Score each 0-4: 0 absent or hostile, 1 rare and mostly failing, 2 partial with major gaps, 3 good with minor gaps, 4 genuinely excellent. Most real interfaces land between 20 and 32 of 40. -If browser automation is available, inspect the live UI at mobile and desktop. If not, inspect source and state the limitation. +| # | Heuristic | Check for | +|---|---|---| +| 1 | Visibility of system status | honest pending and progress, backend-confirmed outcomes, current location, inline validation | +| 2 | Match with the real world | the user's terms, natural order, recognizable icons and metaphors | +| 3 | User control and freedom | cancel, back, undo where the backend supports it, clearing filters and selections, escape from multi-step flows | +| 4 | Consistency and standards | one term per concept, same action same result, standard web controls, one component vocabulary | +| 5 | Error prevention | confirmation before destructive actions, constrained inputs, smart defaults, drafts that survive | +| 6 | Recognition over recall | visible options, labeled icons, inline hints, recent items | +| 7 | Flexibility and efficiency | keyboard paths, bulk actions, accelerators that stay out of a novice's way | +| 8 | Aesthetic and focused design | only what the step needs, clear hierarchy, purposeful emphasis, no decorative clutter | +| 9 | Error recovery | plain language, the exact problem, the recovery, errors near their source, input preserved | +| 10 | Help and documentation | contextual, task-focused, concise help reachable without leaving the task | -## What to evaluate +**Mode applicability:** on Persuade and Experience surfaces, heuristics 7 and 10 may be `n/a`, as may any heuristic that genuinely cannot apply. Write `n/a` with a one-line reason and renormalize: the applicable maximum is 4 times the number scored (/32 when two are `n/a`). Never print /40 over a partial set. -### AI-slop and visual quality +**Bands:** 36-40 Excellent, 28-35 Good, 20-27 Acceptable, 12-19 Poor, 0-11 Critical. With `n/a` items, read the band from the percentage: 90% Excellent, 70% Good, 50% Acceptable, 30% Poor, below that Critical. -Look for gradient text, decorative glass, side-stripe card accents, generic hero metrics, equal icon-card grids, nested cards, centered-stack defaults, category-reflex palettes, repeated tiny section kickers, default numbered section markers, oversized display type, text overflow, and vague filler copy. +## Cognitive load -### Heuristics +Intrinsic load comes from the task: structure it with steps, defaults, and progressive disclosure. Extraneous load comes from the design: eliminate it. Germane load is learning that pays off: support it with consistent patterns and confirming feedback. -Score 0-4: +Checklist; count the failures (0-1 low, 2-3 moderate, 4+ critical): -1. Visibility of system status. -2. Match with user language and mental model. -3. User control and recovery. -4. Consistency and standards. -5. Error prevention. -6. Recognition over recall. -7. Efficiency for frequent users. -8. Aesthetic and focused design. -9. Error recovery. -10. Help and onboarding. +- **Single focus:** the primary task is free of competing elements. +- **Chunking:** information comes in groups of four or fewer. +- **Grouping:** related items sit together by proximity or shared ground. +- **Hierarchy:** the most important thing is obvious at once. +- **One thing at a time:** one decision before the next. +- **Minimal choices:** four or fewer visible options per decision point. +- **Working memory:** nothing must be remembered from a previous screen. +- **Progressive disclosure:** complexity appears only when needed. -### Register fit +Working memory holds about four items: 5-7 at one decision point pushes the limit, 8+ overloads it. In practice: one primary action with one or two secondaries and the rest grouped; five or fewer top-level nav items; one reading path per article with related links gathered at the end; four or fewer sibling choices per docs-sidebar level; one decision per gallery screen. -For product surfaces, ask whether the interface feels trustworthy, familiar, dense enough, and efficient. For brand surfaces, ask whether it has a memorable point of view, specific imagery/type/color, and a non-template composition. +Name violations by pattern: wall of options, memory bridge between steps, hidden location, jargon barrier, flat visual noise floor, inconsistent pattern, simultaneous demands, context switch for a single decision. -### Persona red flags +## Personas -Pick 2-3 relevant personas from context, such as: +Pick two or three by surface; walk each through the primary action and name exactly what breaks. Never write generic persona descriptions. -- First-timer: needs orientation and clear next step. -- Power user: needs efficient navigation and predictable controls. -- Keyboard/screen-reader user: needs semantics, labels, focus, status announcements. -- Mobile user: needs touch targets and structural adaptation. -- Low-trust/high-stakes user: needs confirmation, reversibility, precise errors. +- **Alex, power user:** skips onboarding, wants keyboard paths and bulk actions. Red flags: forced tutorials, no keyboard route to the primary action, slow unskippable motion, one-at-a-time work where batch is natural, confirmations on low-risk actions. +- **Jordan, first-timer:** reads everything, takes labels literally. Red flags: icon-only navigation, unexplained jargon, no visible help, ambiguous next step, no confirmation that an action succeeded. +- **Sam, keyboard and screen-reader user:** tabs linearly, relies on headings and labels, zooms to 200%. Red flags: click-only interactions, invisible focus, color-only meaning, unlabeled controls, patched regions that change without a status announcement, time limits without extension. +- **Riley, stress tester:** empty and huge data, long strings, emoji and RTL, refresh mid-flow, two tabs. Red flags: features that appear to work but fail silently, errors that leak internals or break the UI, empty states with no guidance, input lost on refresh or validation error, UI that claims success the backend did not confirm. +- **Casey, distracted mobile user:** one thumb, interrupted, slow connection. Red flags: key actions out of thumb reach, progress lost on interruption, typing where selection would do, heavy assets on every page, targets under 44px or crowded together, custom drag or scroll controls that fail under touch. -Do not write generic persona descriptions. Walk each through the primary action and name what breaks. +| Surface | Personas | +|---|---| +| Landing page, marketing | Jordan, Riley, Casey | +| Dashboard, admin, data-heavy | Alex, Sam | +| Checkout | Casey, Riley, Jordan | +| Onboarding | Jordan, Casey | +| Forms, wizards | Jordan, Sam, Casey | + +When PRODUCT.md confirms an audience the five do not cover, add one or two project personas (profile, behaviors, red flags) from it. Never invent audience details. ## Report format +Synthesize; do not concatenate. Say where the design review and the scan agree, what the scan caught alone, and which scan findings are false positives. + ```markdown +Method: dual-agent (A: · B: ) | Degraded: single-context () + ## Design Health Score | # | Heuristic | Score | Key issue | -|---|---:|---:|---| +|---|---|---|---| | 1 | Visibility of system status | ?/4 | ... | | ... | ... | ... | ... | -| **Total** | | **?/40** | **Excellent/Good/Acceptable/Poor/Critical** | +| **Total** | | **?/** | **** | -## Anti-pattern verdict +## Design specificity verdict -Does this look generated or generic? What specific tells prove it? +Start here. Authored for this product, or category-interchangeable? The unanchored design judgment first, then the scan summary with counts, locations, and false positives. ## Interaction trust verdict -Pass/fail for backend-confirmed success, honest pending, and local-only affordances. +Pass or fail for backend-confirmed outcomes, honest pending, and local-only affordances, with the evidence. ## Overall impression -One paragraph. +What works, what does not, and the single biggest opportunity. ## What's working -2-3 concrete strengths. +2-3 specific strengths and why they work. ## Priority issues -- [P0/P1/P2/P3] Issue +3-5, most impactful first. + +- [P0-P3] Issue - Location: - Why it matters: - Fix: - - Suggested command: `cheers-design ...` + - Suggested command: `cheers-design ` ## Persona red flags -... - -## Questions to decide +Per persona, the exact elements and interactions that fail. -2-4 targeted questions only if needed. +## Minor observations -## Recommended actions +## Questions to consider -Prioritized command list. +Provocative questions that might unlock a better solution. ``` Severity: -- **P0**: blocks core task, data trust, or accessibility. -- **P1**: major user harm or backend-confirmed trust violation. -- **P2**: meaningful quality issue. -- **P3**: polish. +- **P0 blocking:** prevents the core task, breaks data trust, or blocks access. +- **P1 major:** significant difficulty, a WCAG AA violation, or a backend-confirmed trust violation. If a user would contact support about it, it is at least P1. +- **P2 minor:** an annoyance with a workaround. +- **P3 polish:** no real user impact. -## Persist the snapshot +Be direct and specific ("the save button", not "some elements"), say why it matters to users, give concrete fixes, prioritize ruthlessly, and do not soften criticism. -After finalizing the report, write it to `.cheers-design/critique/` if a slug was computed. +## Deliver, persist, close -1. Write the full report body to a temporary file. Exclude any final conversational question that is not part of the critique report. -2. Run: +1. **Deliver.** Write the full report into the chat response before any persistence. A report that exists only in a snapshot file was never delivered. +2. **Persist** when a slug was computed. Write a copy of the delivered report, from the Method line through Questions to consider, to a temporary file, then: ```bash - CHEERS_DESIGN_CRITIQUE_META='{"target":"","score":,"p0":,"p1":}' \ + CHEERS_DESIGN_CRITIQUE_META='{"target":"","score":,"max_score":,"na_heuristics":"","p0":,"p1":}' \ node /scripts/critique-storage.mjs write ``` - The helper prints the absolute path it wrote. + The helper prints the path it wrote. Delete the temporary file whether the write succeeds or fails; if deletion fails, mention `temp-file cleanup failed: ` without blocking. The helper does not track whether the target changes afterward; polish verifies findings against current code. +3. **Read the trend:** `node /scripts/critique-storage.mjs trend 5`. Add one line after the report and before the questions: -3. Delete the temporary body file whether the write succeeds or fails. -4. Read trend metadata: + > Wrote `.cheers-design/critique/`. Trend for ``: 24 -> 28 -> 32 (out of 40). - ```bash - node /scripts/critique-storage.mjs trend 5 - ``` + Treat a missing `max_score` as 40. When entries differ in maximum, print each with its own denominator (`24/32 -> 30/40`) and note the runs are not like-for-like. On a first run say `First run for , no trend yet.` If persistence fails, report the error in one line and continue. Never show the helper's JSON. +4. **Close with questions.** In the same message, after everything else, ask two to four targeted questions through the structured question tool when available, each tied to specific findings with two or three concrete options: + - **Priority direction:** which of the top two or three issue categories to tackle first. + - **Design intent:** whether a tonal mismatch the critique found was intentional, offering directions that would fix it. + - **Scope:** top three, all issues, or P0/P1 only. + - **Constraints**, only when findings span many areas: what must stay as is. + + Skip the questions only when the report lists fewer than three priority issues, and then print the literal line `Questions skipped: ` naming the count. A run that ends with neither questions nor that line is incomplete. + +## Recommended actions -5. Add one concise line after the report: +After the user answers, list commands in priority order, by stated priority first and impact second: - > Wrote `.cheers-design/critique/`. Trend for ``: 24 -> 28 -> 32. +1. **`cheers-design `:** what to fix, with enough context from the findings that the command knows where to focus. -If this is the first run, say: `First run for , no trend yet.` If persistence fails, report the error briefly and continue; the chat report remains the primary deliverable. +Map every priority issue to a command, skip commands that address nothing, respect the chosen scope and off-limits areas, and end with `cheers-design polish` when any fixes were recommended. Then tell the user they can run these one at a time, all at once, or in any order, and re-run `cheers-design critique` after fixes to see the score move. diff --git a/skills/cheers-design/reference/delight.md b/skills/cheers-design/reference/delight.md index a716155..786d2ff 100644 --- a/skills/cheers-design/reference/delight.md +++ b/skills/cheers-design/reference/delight.md @@ -1,60 +1,81 @@ # Delight -Add memorable, appropriate moments to a Cheers UI. Delight should amplify successful use, not distract from it. +Make a Cheers UI memorable at moments that earn it. Delight is not a layer of generic whimsy; it is product character revealed through a useful interaction, a humane response, or an unexpectedly considered detail. -## Register +Know the product's emotional range. Ask only when it, or the stakes, cannot be inferred from PRODUCT.md, DESIGN.md, and the surface. -- **Product**: delight belongs at earned moments: first success, completion, recovery, milestone, useful shortcut discovery. -- **Brand**: delight can be broader: copy voice, section transitions, imagery, interaction details, seasonal or narrative touches. +## Visitor mode -## Find earned moments +- **Persuade + Experience:** personality may run through voice, composition, motion, and discovery, provided the artifact stays the focus. +- **Operate + Read:** concentrate delight at meaningful moments such as first use, completion, recovery, or mastery. Reliability carries everything else. -Look for: +Delight works inside the established world and voice. It never introduces a new identity. -- empty states that could welcome and guide -- backend-confirmed success states -- long waits that need reassuring progress -- error recovery moments -- milestones or first-time actions -- hover/focus micro-interactions that make controls feel finished +## Two isolated assessments -Ask what tone is appropriate if unclear: playful, professional, quirky, elegant, calm. +Run these in order, and do not let scan findings anchor the design assessment. With subagents available, run them independently. -## Principles +1. **Design assessment:** inspect the target, DESIGN.md, product voice, repeat frequency, and emotional context. Look for: + - effort worth acknowledging; + - waiting that can become informative; + - an empty or first-use state that can orient; + - an error or recovery moment that needs empathy; + - an interaction whose physical or verbal response could express the brand; + - a useful capability people might enjoy discovering. -- Delight must never delay or block the task. -- Delight must not imply success before backend confirmation. -- Delight should be brief, optional where possible, and respectful after repetition. -- The more serious the user state, the quieter the delight. -- Reduced-motion users still get a polished static version. + Do not manufacture a celebration for an ordinary click. +2. **Mechanical scan:** run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the target page. -## Patterns +Synthesize both before editing. -### Backend-confirmed celebration +## State the delight thesis -Celebrate only after the confirmed success state is rendered. Motion can emphasize that new state, but it should not fire on click before success. +In one sentence, state what the user should feel and why that feeling belongs to this product. Then name the moment, its trigger in the interaction contract, and the smallest system that delivers it: -### Helpful empty states +- a distinctive response to a meaningful action; +- product-specific language that clarifies while carrying voice; +- an interaction or transition with a recognizable material behavior; +- an illustration, sound (opt-in), or environmental detail grounded in the product world; +- a discovery reward that reveals real utility. -Use the empty state to explain what will appear, why it matters, and the first useful action. Make the tone specific to the product. +Derive the treatment from the product mechanism and visual world, not a stock catalog. -### Local micro-interactions +## Apply -Use hover, focus, active, reveal, and small local toggles to make controls feel considered. Keep them independent of durable state. +Read [craft-floor.md](craft-floor.md) first; for authored motion, also load [animate.md](animate.md). -### Waiting states +- **Success:** fires only once the backend-confirmed state is rendered, never on click. Match the response to effort and consequence: milestones can expand; routine saves should simply feel certain. +- **Waiting:** truthful progress, useful context, or product-specific activity ("Importing 24 of 120 rows"). Never fake work, imply completion, or delay the result to stage a flourish. +- **Empty and first use:** make the next action clear before adding personality. +- **Error and recovery:** lead with the problem and the recovery. Warmth may lower stress; jokes must not trivialize loss, money, privacy, or blocked work. +- **Repeated interaction:** still satisfying on the hundredth use. Vary only when it stays coherent and predictable enough to trust. +- **Discovery:** reward curiosity without hiding required functionality. +- **Local micro-interactions:** hover, focus, active, and reveal details may use signals as local affordances; keep them independent of durable state. -Use reassuring, specific copy. "Importing 24 rows..." is better than generic jokes. For long jobs, show truthful progress when available. +Copy uses the product's language. Generic whimsy is worse than neutral clarity. -## Avoid +## Protect the experience -- Confetti for routine saves. -- Humor in severe errors. -- Repeated animations that become annoying. -- Large JS bundles for tiny effects. -- Sound without explicit opt-in. -- Delight that hides poor UX. +Delight must not: + +- delay, block, or obscure the primary task; +- override native conventions or accessibility; +- add unrequested factual claims; +- play sound without opt-in or ignore mute settings; +- become mandatory, unskippable, or exhausting on repeat; +- cost a dependency, JS helper, or asset weight out of proportion to the moment. + +Respect screen readers, keyboard, touch, localization, and cultural context. Nonessential loops stop when hidden. Reduced-motion users get a finished static version. Use `cheers` for implementation; format changed templates with `cargo cheers fmt --rustfmt `. ## Verify -Does the moment feel earned? Is it still pleasant after repeated use? Does it work with keyboard, screen readers, reduced motion, slow network, and failed backend actions? +Inspect in one batched round, fix everything in one batch, confirm with at most one more round. Answer each with rendered or source evidence: + +- The moment is specific enough that a neighboring product could not use it unchanged. +- It improves comprehension, confidence, motivation, or emotional recovery. +- It appears only after backend confirmation, and a failed action shows no celebration. +- The interface stays fast and obvious without the flourish, on a slow network too. +- Repetition does not turn charm into friction; muted, keyboard, touch, reduced-motion, and localized paths work. +- It feels like the established world, and the rerun scan has no unexplained findings. + +When the personality feels earned, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/distill.md b/skills/cheers-design/reference/distill.md index 21ac4f6..031dee5 100644 --- a/skills/cheers-design/reference/distill.md +++ b/skills/cheers-design/reference/distill.md @@ -1,56 +1,84 @@ # Distill -Strip a Cheers UI to its essence. Remove obstacles, not necessary capability. +Strip a Cheers UI to its essence. Remove what does not earn its place: redundant elements, repeated information, decorative noise, cosmetic complexity. Simplicity removes obstacles between users and their goals, not necessary capability. -## Assess +## Visitor mode -Find complexity sources: +- **Persuade + Experience:** distill toward one message and one action per section. Keep the world and its signature move; cut what dilutes them. +- **Operate + Read:** distill toward the task path and the reader's question. Match complexity to the real task: an expert workflow stays as capable as it needs to be. -- too many primary actions -- repeated explanations -- redundant cards, wrappers, or borders -- too many colors, fonts, variants, and statuses -- all data visible at once with no hierarchy -- local affordances carrying complexity that belongs in the rendered state or flow -- modal flows where inline, page, or progressive disclosure would work +Distilling works inside the established world. Cutting so deep that the identity changes is a redesign and routes through [new-work.md](new-work.md). -Identify the one primary user goal before cutting. +## Two isolated assessments -## Simplify +Run these in order, and do not let scan findings anchor the design assessment. With subagents available, run them independently. + +1. **Design assessment:** find the complexity sources, with rendered or source evidence: + - too many elements: competing primary actions, redundant information, clutter; + - excessive variation: colors, fonts, sizes, and component variants without purpose; + - information overload: everything visible at once, no progressive disclosure; + - visual noise: borders, shadows, backgrounds, wrappers, nested cards; + - confusing hierarchy: unclear what matters most; + - feature creep: too many options, paths, or steps; + - interaction weight: signals, JS helpers, or several coordinated update regions carrying complexity that a form, a page, or the rendered state could carry. + + Then find the essence: the one primary user goal, what is necessary versus nice to have, and what can be removed, deferred, or combined. If the goal is unclear from the code, briefs, and PRODUCT.md, ask rather than guess. +2. **Mechanical scan:** run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the target page. + +Synthesize both before editing. + +## State the system + +Before editing, name the core purpose, the essential elements, what moves behind disclosure, what consolidates, and what is removed. Removing a capability the product offers is a product decision: confirm it with the user first. + +## Apply + +Read [craft-floor.md](craft-floor.md) first. ### Information architecture -- Keep one primary action per surface. -- Move rare actions to secondary placement. -- Collapse advanced controls behind clear disclosure. -- Combine duplicate concepts and terms. -- Prefer recognition over recall: show current state and next step. +- One primary action per surface, few secondary actions, everything else tertiary or disclosed. +- Hide advanced or rare controls behind a clear entry point: native `
`, a secondary page, or a step. Not a modal by reflex. +- Merge duplicate concepts, terms, buttons, and forms. If it is said elsewhere, do not repeat it here. +- Prefer recognition over recall: show current state and the next step. ### Visual structure -- Remove decorative containers. -- Replace nested cards with spacing, headings, and dividers. -- Reduce palette and type roles. -- Keep enough hierarchy for the primary action to remain obvious. +- Reduce to the world's committed color roles (on a Restrained surface, one or two plus neutrals); one family, three or four sizes, two or three weights. +- Remove decorative containers. Replace nested cards with spacing, headings, and dividers; use one spacing scale. +- Pick left or center alignment and stick with it. +- Prefer a linear flow over complex grids or sidebars where the content allows. +- Keep enough hierarchy that the primary action stays obvious. ### Interaction - Prefer normal navigation and forms where dynamic behavior adds little. -- Prefer one understandable update region over several coordinated visual changes when possible. -- Use local client affordances only where they reduce cognitive load. -- Remove unnecessary JS helpers. +- Prefer one understandable update region over several coordinated changes. +- Use smart defaults; ask only when necessary. Can the flow lose a step? +- Keep signals only where they reduce cognitive load; remove JS helpers that no longer earn their place. ### Copy -Cut repeated intro text and vague claims. Preserve specific labels, hints, and error recovery copy. +Cut every sentence in half, then do it again. Active voice ("Save changes", not "Changes will be saved"), plain language, no headers restating intros, no marketing fluff or hedging. Preserve specific labels, hints, and error recovery copy. + +### Code + +Remove dead CSS, unused components, and orphaned helpers. Flatten deep template nesting and collapse component variants that three can cover. Use `cheers` for implementation; format changed templates with `cargo cheers fmt --rustfmt `. -## Do not +## Never -- Remove accessible labels or status messages. -- Hide necessary error or permission information. -- Remove backend validation because the UI looks simpler. -- Oversimplify a genuinely complex expert workflow. +- Remove necessary functionality, information users need to decide, or backend validation because the UI looks simpler. +- Remove accessible labels, status messages, error, or permission information. +- Make things so minimal they turn mysterious, or flatten hierarchy completely. +- Oversimplify a genuinely complex domain. ## Verify -Task completion should be faster, the primary action clearer, and code/state simpler. If simplification removed needed state coverage, run `harden` next. +Inspect desktop and mobile in one batched round, fix everything in one batch, confirm with at most one more round. Answer each with rendered or source evidence: + +- The task completes faster, and it is obvious what to do and what matters most. +- Every necessary capability is still reachable. +- The simpler design loads faster. +- State coverage (pending, error, empty, success) survived the cuts, and the rerun scan has no unexplained findings. + +Report what was removed, why, and where anything moved. If simplification exposed missing state coverage, run `cheers-design harden`. When the cuts feel right, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/document.md b/skills/cheers-design/reference/document.md index db17735..65f4390 100644 --- a/skills/cheers-design/reference/document.md +++ b/skills/cheers-design/reference/document.md @@ -1,44 +1,80 @@ # Document -Create or refresh `DESIGN.md` for a Cheers app so future UI work stays visually consistent. This is the visual companion to `PRODUCT.md`. +Create or refresh `DESIGN.md` at the project root (or the app root in a workspace with several apps) so future UI work stays visually consistent. It is the visual companion to `PRODUCT.md`: strictly visual, never a copy of product truth or surface strategy. -DESIGN.md should follow the Google Stitch DESIGN.md shape: YAML frontmatter with machine-readable tokens, followed by a markdown body with six fixed top-level sections. Tokens are normative; prose explains how to apply them. +DESIGN.md follows the [DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md) used by Google Stitch: YAML frontmatter with machine-readable tokens, then up to eight markdown sections in a fixed order. Tokens are normative; prose explains where and why to apply them. -## Before writing +## When to run -If `DESIGN.md` exists, do not overwrite it silently. Read it and ask whether to merge, refresh, or replace. +- New-work found a coherent incumbent system but no DESIGN.md. +- A new world or an approved system change has been built and reviewed (new-work section 7 records it here). +- An existing DESIGN.md has drifted from the code. +- Before a large redesign, to capture the current state as reference. -Scan the project first: +On a standalone `document` run, never overwrite an existing DESIGN.md silently. Show it and ask: refresh, overwrite, or merge. The record-from-build pass below already has the user's world approval and writes without asking. If another tool in the project expects a specific format, preserve that format and fold these requirements into it. -- global CSS and included CSS files -- CSS custom properties and token files -- shared UI components and page shells -- buttons, forms, cards/containers, nav, badges, empty/error/loading states -- icon and image assets -- motion conventions -- rendered output if practical +## Choose the path -## Modes +- **Scan mode (default):** the project has tokens, components, or rendered output. Extract, then confirm the descriptive language. +- **Seed mode:** the project is pre-implementation. Route through new-work's world workshop and write a directional seed. -### Scan mode +Decide by scanning first. If the scan finds no tokens, no components, and no rendered pages, offer seed mode; do not switch silently. `cheers-design document --seed` requests the workshop but never authorizes replacing coherent code: when an incumbent system exists, offer scan mode, or route an explicit identity replacement through [new-work.md](new-work.md). -Use when code exists. Extract actual visual system values and component behavior from the repo. +## Record from the build -### Seed mode +At the finish of a new world or approved system change, DESIGN.md is written from what shipped, preferably by a fresh subagent given the project root, the changed files, the direction contract from the surface brief, PRODUCT.md, this file, and the write boundary. Without subagents, step out of the build context and follow these rules yourself. -Use when the app has little or no UI yet. Ask 4-5 questions, wait for answers, then write a minimal starter DESIGN.md marked ``. Re-run `document` later after implementation. +- **The build is ground truth.** Every token and rule must be evidenced by the built code, never by the plan. The contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence. +- **Extension vs new world.** A new world or approved system change writes DESIGN.md from durable, reused rules in the build. On an approved system change, update an existing DESIGN.md rather than replacing it: preserve confirmed incumbent decisions and reconcile them with the build. A redesign replaces it. An ordinary extension preserves the incumbent DESIGN.md and its files; compare the build against it and report pre-existing drift without repairing it unasked. When the recorded system still matches, leave it untouched and report the evidence checked. Never write merely to prove the pass ran. +- **Do not legitimize defects.** A rule goes wrong in two ways: a prohibition that bans a device the world itself uses natively, and a value recorded to make a finding disappear. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility. +- **Never canonize a craft-floor refusal.** An element [craft-floor.md](craft-floor.md) refuses (kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text) is recorded as a defect the build carries, never as a rule for future surfaces to inherit. One shipped violation written into DESIGN.md becomes the house style. +- **Keep surface strategy out.** The first surface's composition, narrative, and contract stay in its surface brief. +- **Do not re-interview.** Take the qualitative language from the direction contract and the confirmed answers instead of asking again. +- **Budget the reading.** Batch reads, take this file and the stylesheets first, sample components rather than walking the tree, and start writing by the midpoint. -Questions for seed mode: +Return: paths written, or "No changes" with the files checked; a five-line system summary (palette, type ramp, named rules); and one line naming the defects or drift not canonized or repaired, and why. -- product or brand register? -- color strategy: Restrained, Committed, Full palette, or Drenched? -- theme scene: who uses this, where, under what light and mood? -- typography tone and density? -- 2-3 references or anti-references? +## Scan mode -## DESIGN.md frontmatter +### 1. Find the design assets -Open DESIGN.md with YAML frontmatter. Include only tokens the project actually uses; do not invent empty scales. +In priority order: + +1. CSS custom properties: `--color-`, `--font-`, `--space-` and `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations, with name, value, and file. +2. Token files, theme stylesheets, and the global stylesheet's base type and color assignments. +3. Shared components (Rust types implementing `Render`) and page shells: buttons, forms and inputs, containers, navigation, badges, dialogs and popovers, empty, error, loading, and pending states. Note variants and default styles. +4. Icon and image assets, and motion conventions. +5. The running app, when available: sample computed styles from `body`, headings, links, buttons, and key containers. This catches values tokens miss. + +### 2. Extract and stage the frontmatter + +- **Colors:** group by role into Primary, Secondary, Tertiary, Neutral. With one accent, write Primary plus Neutral; never invent Secondary or Tertiary. +- **Typography:** map observed sizes and weights to display, headline, title, body, label. Note stacks and the scale ratio. +- **Layout:** grid, containers, breakpoints, spacing rhythm, density. +- **Elevation:** the shadow vocabulary, or an explicit statement that the system is flat or tonally layered. +- **Shapes:** radius, corner, border, clipping, recurring silhouettes. +- **Components:** per common component, shape, color assignment, hover and focus treatment, padding, and states. + +Skip anything the project does not have. Stop at what is reused; one-offs and empty scales pollute the system. + +### 3. Ask for the qualitative language + +Ask in at most two structured rounds of up to three questions, waiting between rounds: + +- **Creative North Star:** one named metaphor for the system. Offer two or three options grounded in the incumbent world and PRODUCT.md's brand personality. +- **Overview voice:** mood words, the aesthetic philosophy in two or three sentences, and any confirmed visual anti-reference. +- **Color character:** descriptive names for key colors ("Deep Muted Teal-Navy", not "blue-800"), two or three options each. +- **Elevation and component philosophy:** flat, layered, or lifted; the feel of buttons, containers, and inputs in one phrase. + +Carry a PRODUCT.md line only when it is a durable constraint on the visual system: a binding logo, identity asset, accessibility need, or brand commitment. + +### 4. Write, then confirm + +Write the frontmatter and body below. Show the result, call out the non-obvious choices (color names, named rules, atmosphere language), and offer to refine any section. + +## Frontmatter + +Include only tokens the project uses. Token groups are limited to `colors`, `typography`, `rounded`, `spacing`, and `components`; no `motion:`, `shadows:`, or `breakpoints:` groups. The only other valid top-level keys are `name`, `description`, `version`, and `omitted` (a list of deliberately omitted sections). ```yaml --- @@ -46,6 +82,7 @@ name: description: colors: primary: "#b8422e" + primary-deep: "#8f3222" surface: "#faf7f2" ink: "#201916" typography: @@ -71,71 +108,90 @@ components: textColor: "{colors.surface}" rounded: "{rounded.md}" padding: "12px 16px" + button-primary-hover: + backgroundColor: "{colors.primary-deep}" --- ``` -Rules: +- Token refs use `{path.to.token}`. Components may reference primitives; primitives never reference each other. +- `colors` must include a `primary` key; when the project's own names differ, alias `primary` to its main accent. +- Colors accept any valid CSS color string. Hex is the portable default; keep an incumbent `oklch()`, `hsl()`, or wide-gamut value when it is the project's normative source. One source of truth: prose names a token and its role but never restates a different value. +- Typography props: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`. Include only the real ones. +- Component tokens use at most `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Variants are sibling keys (`button-primary-hover`). Shadows, focus rings, motion, and backdrop effects go in the body prose. +- Keep the project's own token names (`--color-surface-raised` becomes `surface-raised`). Never rename a mature system to Material defaults. +- Values must match the real CSS custom properties, stylesheets, or component defaults. +- Fluid `clamp()` sizes and multi-value padding may draw linter warnings, since the spec's Dimension is a single px, em, or rem value. Keep them only when they are the normative source. -- Token refs use `{path.to.token}`, such as `{colors.primary}` or `{rounded.md}`. -- Keep frontmatter values aligned with real CSS tokens, theme files, or component defaults. -- Color values should be hex for Stitch compatibility. If the project treats OKLCH as canonical, put the nearest hex in frontmatter and record the canonical OKLCH value in the markdown body. -- Component frontmatter should stay compact: background/text color, typography, rounded, padding, width/height/size. Put shadows, focus rings, motion, complex states, and Cheers-specific contracts in the markdown body. -- Use semantic token names from the project when they exist. Do not rename a mature system to generic Material-style keys. +Do not write a `.cheers-design/design.json` sidecar. Upstream Impeccable writes a JSON sidecar for its live design panel; `cheers-design` has no consumer for it, so the frontmatter carries the tokens and the body carries everything else. -## Markdown body +## Body -Use exactly these six top-level sections, in this order. Optional numbering or subtitles are fine, but each header must contain the literal section name. +Use these headings verbatim, in this order. Omit a section that does not apply rather than inventing rules; never rename one ("Colors", not "Color Palette & Roles"). ```markdown # Design System: [Project] -## 1. Overview - -Creative north star, register, mood, density, and what the system rejects. - -## 2. Colors - -Palette tokens, semantic roles, contrast rules, status colors, dark/light behavior if any. +## Overview +**Creative North Star: "[Named metaphor]"** +[Two or three paragraphs: personality, density, philosophy, confirmed visual rejections. End with **Key Characteristics:** bullets.] -## 3. Typography +## Colors +[Palette character in one sentence, then Primary / Secondary / Tertiary / Neutral, each color as **Descriptive Name** (value): where and why. Contrast rules, status colors, light/dark behavior.] -Font stacks, scale, weights, line-height, prose measure, data-number rules, and font-loading behavior. +## Typography +[Display, body, and label families with fallbacks and character. Hierarchy: display, headline, title, body (with measure), label. Tabular numerals, font loading.] -## 4. Elevation +## Layout +[Grid or spatial model, containers, density, spacing rhythm, responsive changes. Exact values only when observed.] -Shadow, border, tonal-layer, and depth rules. If the system is flat, say so explicitly. +## Elevation & Depth +[Shadows, tonal layering, or both. If flat, say so and say how depth is conveyed. Shadow vocabulary with exact values.] -## 5. Components +## Shapes +[Corner and radius strategy, borders, clipping, recurring geometry.] -Buttons, links, inputs, forms, cards/containers, nav, badges, empty/error/loading states, dialogs/popovers. +## Components +[Per component: character line, shape, colors, states (hover, focus-visible, active, disabled, pending, error, success), distinctive behavior. Buttons, links, inputs, containers, navigation, badges, dialogs, empty/error/loading states, signature components.] -## 6. Do's and Don'ts - -Concrete guardrails, including no gradient text, no decorative glass, no side-stripe card accents, and no optimistic success. +## Do's and Don'ts +### Do: +- **Do** [prescription with exact values or a named rule]. +### Don't: +- **Don't** [prohibition confirmed by the incumbent system or the user]. ``` -Fold layout, spacing, motion, interaction, and state guidance into these six sections rather than adding extra top-level sections: +- **Named Rules:** `**The [Name] Rule.** [short doctrine]`, one to three per section where the system has real invariants. They are citable and sticky for later agents. +- **Descriptive first, value in parens:** "gently curved edges (8px)", not a class name. +- **Functional over decorative:** say where and why each token is used. +- **Decisive where evidence is decisive:** hard language for invariants, softer for provisional guidance. Audit tests only when grounded in the observed system or a confirmed decision. +- **Motion has no token group.** The world's motion grammar goes in Overview; per-component motion goes in Components. +- **Guardrails are system-wide.** Do not turn a task-specific concept into a global prohibition. Interaction trust always applies: no optimistic success, no pending state that reads as done. -- layout and spacing usually belong in **Overview**, **Components**, or **Do's and Don'ts** -- motion belongs in **Components** or **Do's and Don'ts** -- backend-confirmed state and pending/error/success behavior belong in **Components** and **Do's and Don'ts** +## Cheers-specific content -If another tool in the project expects a specific format, preserve that format and fold these requirements into it. +Capture design-relevant implementation facts without turning DESIGN.md into an API manual: -Do not write a `.cheers-design/design.json` sidecar unless a Cheers tool that consumes it exists. Upstream Impeccable uses `.impeccable/design.json` for its live design-system panel; `cheers-design` does not currently have an equivalent consumer. +- CSS custom property names used by Cheers templates and stylesheets; +- components whose appearance depends on client behavior or local affordance signals; +- the state vocabulary for pending, error, success, empty, and permissions, and which states appear only after backend confirmation; +- conceptual update regions that affect layout or motion; +- reusable UI patterns and their accessibility contracts. -## Cheers-specific content to capture +These belong in Components and Do's and Don'ts. For exact syntax and implementation rules, defer to the main `cheers` skill. -Capture design-relevant implementation facts without turning DESIGN.md into an API manual: +## Seed mode -- CSS token names used by Cheers templates -- components that depend on client behavior -- common state vocabulary for pending, error, success, empty, and permissions -- conceptual update boundaries that affect layout or motion -- reusable UI patterns and their accessibility contracts +For projects with no visual system to extract. It produces a user-chosen world scaffold, not a fabricated token spec. -For exact syntax and implementation rules, link or defer to the main `cheers` skill. +1. **Route through the workshop.** PRODUCT.md is the prerequisite; complete [init.md](init.md) first when it is missing. Then load [new-work.md](new-work.md), resolve visual authority, and name a concrete first surface (the user's target, or ask). Run **Create or replace the visual world** and **Commit the world**, then stop after the seed and the surface brief; do not implement. If new-work already ran the workshop this session, use its chosen direction without asking again. +2. **Write the seed.** Open with ``. Frontmatter carries only `name` and `description`. Use the canonical sections: Overview (thesis, material, imagery stance, motion grammar, reusable signature; not the first surface's composition), Colors and Typography (strategy, roles, and character, with values or faces only when established, otherwise `[to be resolved during implementation]`), Layout, Elevation & Depth, and Shapes as invariants, no Components section, and Do's and Don'ts holding only durable guardrails from the world choice. +3. **Confirm.** Show the seed, say plainly that it is a seed, and tell the user to re-run `cheers-design document` once code exists. When the world is built through new-work, its finish replaces the seed with a scan of the build. ## Verify -The doc should be concrete enough that another agent can build a new screen without inventing colors, spacing, type, state behavior, or Cheers interaction trust rules. +Check with evidence, not a bare yes: + +- every frontmatter value traces to a file and a real CSS value or component default; +- headings match the canonical names and order, and no token is restated with a different value in prose; +- no rule canonizes a craft-floor refusal, no value is recorded to make a reviewer finding disappear, and no prohibition bans a device the world uses natively; +- another agent could build a new screen from it without inventing colors, spacing, type, state behavior, or Cheers interaction trust rules. diff --git a/skills/cheers-design/reference/extract.md b/skills/cheers-design/reference/extract.md index d0ee85c..52c8ca1 100644 --- a/skills/cheers-design/reference/extract.md +++ b/skills/cheers-design/reference/extract.md @@ -1,62 +1,81 @@ # Extract -Extract repeated UI patterns into reusable Cheers components and design tokens. The goal is a more coherent design system, not abstraction for its own sake. +Pull repeated UI patterns into reusable Cheers components and CSS custom properties. The goal is a more coherent design system, not abstraction for its own sake. Extraction is a refinement: the incumbent identity, behavior, copy, and every call site's appearance stay the same unless the user asks otherwise. -## Discover +## 1. Discover the system -Find existing conventions first: +Find the existing conventions first: -- shared components/modules -- design tokens and CSS variables -- layout/base component and page shell -- forms, buttons, nav, badges, empty/error/loading states -- icons, imagery, and motion conventions -- tests or examples that define UI contracts +- shared component modules (Rust types implementing `Render`), the layout or page shell, and how components are named and exported; +- CSS custom properties, token files, and the stylesheets that own them; +- DESIGN.md frontmatter tokens and component entries, when present; +- forms, buttons, navigation, badges, and empty, error, loading, and pending states; +- icons, imagery, and motion conventions; +- tests or examples that define UI contracts. -If no design system or shared component area exists, ask before creating one. +If no design system or shared component area exists, do not create one yet. Ask where it should live and how it should be structured. -## Identify extraction candidates +## 2. Identify candidates -Good candidates: +Extract only what is used three or more times with the same intent: -- repeated markup used 3+ times with the same intent -- repeated form rows, error blocks, empty states, status badges, toolbars, nav items -- repeated CSS values that should become semantic tokens -- repeated pending/success/error interaction patterns -- repeated update regions with the same conceptual boundary +- repeated markup: form rows, error blocks, empty states, status badges, toolbars, nav items, containers; +- hard-coded colors, spacing, type, radii, and shadows that should become semantic tokens; +- inconsistent variations of one concept (three slightly different primary buttons); +- repeated type styles: the same size, weight, and line-height combination; +- repeated easing, duration, or keyframe combinations; +- repeated pending, success, and error interaction patterns, and update regions with the same conceptual boundary. -Do not extract one-off context-specific UI. Duplication is better than a bad abstraction. +Duplication beats a bad abstraction. Two elements that look alike but serve different purposes stay separate. -## Plan the extraction +## 3. State the plan before editing -For each candidate, define: +For each candidate, name: -- component or token name -- semantic purpose and non-goals -- props/content slots in design terms -- accessibility contract -- state variants it owns -- CSS classes/tokens it owns or consumes -- migration path for existing call sites -- tests or examples to update +- the component or token name, matching existing conventions; +- its semantic purpose and non-goals; +- content slots and variants in design terms; +- the accessibility contract (landmark or role, label, focus, keyboard path, live status); +- the states it owns, including which appear only after backend confirmation; +- the CSS classes and custom properties it owns or consumes; +- the migration path for existing call sites, and the tests or examples to update. -Use the main `cheers` skill for exact `Render`, generated helpers, and test mechanics. +Grow the system incrementally: extract what is clearly reusable now, not what might be someday. Read [craft-floor.md](craft-floor.md) before editing; an extracted component must not canonize a pattern the floor refuses. -## Token extraction +## 4. Extract -Create or extend a small semantic vocabulary: +- **Components:** a small content API with sensible defaults and only the variants call sites need. Semantic HTML, focus, and keyboard behavior are built in, not left to callers. Signals inside a component stay local affordances; durable state arrives as rendered input. Use the main `cheers` skill for `Render`, generated helpers, and test mechanics. +- **Tokens:** a small semantic vocabulary layered over primitives, declared as CSS custom properties in the project's stylesheet conventions: -- colors: surface, text, muted text, border, accent, success, warning, error, info -- spacing: component gaps, section gaps, inline gaps -- type: body, label, title, heading, data -- radii, shadows, easing only if actually used +```css +:root { + --color-surface: oklch(98% 0.01 80); + --color-text-muted: oklch(45% 0.02 80); + --color-danger: oklch(55% 0.18 25); + --space-inline: 0.5rem; + --space-section: 4rem; + --radius-control: 6px; +} +``` -Use tokens where they clarify intent. Do not create a token for every value. +Cover surface, text, muted text, border, accent, and status colors; inline, component, and section spacing; body, label, title, heading, and data type; radii, shadows, and easing only where actually used. A token needs semantic meaning; do not create one for every value. -## Migrate +## 5. Migrate -Replace call sites systematically, run formatter/tests, and delete dead CSS or components. Preserve user-facing behavior and state semantics. +Replace call sites systematically, format changed templates with `cargo cheers fmt --rustfmt `, run the targeted tests, and delete the dead CSS and components. Preserve user-facing behavior and state semantics. + +## 6. Document + +When tokens or shared components changed, update DESIGN.md to match per [document.md](document.md): frontmatter values, the Components section, and any named rule the extraction made true. Do not rewrite unrelated sections, and report pre-existing drift rather than repairing it unasked. ## Verify -The extracted pattern should be easier to use correctly than copying markup. It must preserve accessibility, backend-confirmed state, and visual consistency. +Check with evidence in one bounded pass, and fix what it shows in one batch: + +- each migrated call site renders as before at desktop and mobile widths, including its pending, error, empty, and success states; +- the extracted pattern is easier to use correctly than copying markup; +- accessibility, backend-confirmed state, and keyboard and focus order are preserved; +- no hard-coded value remains where a token now exists, and no token exists without a consumer; +- the [mechanical scan](../SKILL.md#mechanical-scan-optional), when available, shows no new findings. + +Never extract one-off context-specific UI, components so generic they say nothing, or abstractions that ignore the existing conventions. diff --git a/skills/cheers-design/reference/finish-review.md b/skills/cheers-design/reference/finish-review.md new file mode 100644 index 0000000..8994b1c --- /dev/null +++ b/skills/cheers-design/reference/finish-review.md @@ -0,0 +1,41 @@ +# Finish review + +You are the finishing reviewer for a Cheers design build: fresh eyes on a done artifact, outside the build thread's attention. You edit nothing; the builder applies your fixes. Review from the provided files only: do not start servers or re-render pages. + +Budget your reading: read only the provided inputs plus the craft floor, never any other skill reference file. Take the captures, the surface brief, and [craft-floor.md](craft-floor.md) first, sample the changed templates and stylesheets rather than walking the tree, and stop reading by roughly the tenth turn and write. Name anything that went unread in one line above your sections. + +## Inputs + +Expect: the original request; the confirmed user answers; the changed files; captures in `.cheers-design/review//` for each changed page (`desktop.png`, `mobile.png`, plus any named user viewport); the surface brief with its direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md; any mechanical scan findings; and the craft-floor path, and, when one exists, an image mock as a critique reference (provocation about what it dared, never a spec). When an expected input other than a capture is missing, say so in one line at the top and review what is reviewable. When you can view images, open the captures first and inventory the salient elements in your own words before reading the contract or any builder summary: a review anchored on the contract inherits whatever the builder's abstraction dropped. + +## Checks, in order + +0. **Evidence.** The required captures exist and are valid: no black or blank regions, content matching what the filename claims, the document top visible on full-page captures, dimensions that fit the named viewport. If any capture is missing or invalid, return `disposition: recapture` and a single `recapture` section listing each file and what a valid capture shows, then stop. A verdict built on broken evidence launders the breakage into an approval. +1. **Persistence.** PRODUCT.md exists, and the surface brief holds all six contract blocks. When DESIGN.md predates this build (an extension or redesign), the build matches it or the deviation is approved. On a new world DESIGN.md is written after this review, so its absence is not a finding. +2. **Contract, promise by promise.** For each block, does the render keep the promise? Apply the memory test to the first viewport: what would someone describe an hour later? A missing signature element, a changed topology, or content added without approval outranks every craft point. Hold three rows every time: **type** (the display lettering's character, width, weight, and contrast against OWN-WORLD), **material** (faked physicality such as CSS bevels, embossing, or imitation textures is contradicted on its face), and **ground** (the page field's value and temperature against a color OWN-WORLD names; drift toward cream on light grounds or blue-black slate on dark is the direction to hunt; with no named color, say there is no ground authority instead of inventing one). +3. **Ceiling.** Name the world's native devices the build left unused: frame, depth, lettering treatment, ornament density, motion, the form's web technique. +4. **Truth.** Demonstration data is labeled synthetic; no invented commercial claims; unanswered claims appear as marked placeholders. Produced assets are visibly present, not buried at near-zero opacity or behind a wash, and not replaced by a gradient or a many-vertex `clip-path`; scan findings of either kind are material fixes. +5. **Interaction trust.** Success, removal, completion, and reordering appear only after backend confirmation; pending states are honest; local affordances do not pose as durable state. +6. **Floor.** Hold the captures against the craft floor's Refuse list: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, a system face as the display voice of an own-world page, gradient text, side stripes, and the rest. A refused element is a material fix unless the user's request or confirmed answers explicitly asked for it; the builder's own contract does not earn it. Kickers and eyebrows are never earned. + +Do not run a second mechanical scan. + +## Disposition + +The first line of your return is `disposition: recapture`, `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. These four words are the whole vocabulary. The word is derived, never felt: recapture when the evidence check failed; rebuild when material is contradicted on the focal element or contradiction is the page rather than the exception, in which case stop ordering repairs and make the first material fix a rebuild directive naming the regions to re-derive and the assets to produce; fix when material fixes remain; ship only when nothing is contradicted or missing. Calibrate against the contract and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is. + +## Output + +After the disposition line, return exactly five sections: + +- `persistence`: pass or fail with specifics. +- `fidelity`: per salient element, match, acceptable adaptation (citing the user answer, accessibility need, or product truth that forced it; an uncited deviation is a defect), missing, contradicted, or added without approval. Include the type, material, and ground rows. +- `ceiling`: unused native devices, or "reached". +- `material_fixes`: ordered, most material first, contract failures ahead of craft, one line each tied to a check or contract promise, at most eight. A fix that needs an asset says "produce: as an asset", never a style tweak. +- `keep`: one line naming what must not be diluted while fixing. + +No praise, no summary prose. + +## Verdict pass + +When the builder returns with recaptures after a fix batch, you are scoring, not re-hunting. Recaptures that fail the evidence check get `disposition: recapture`. A return after a rebuild, or one carrying user-supplied captures that contradict a prior verdict, is a new full review. Otherwise re-read the same capture paths; the builder's narration of what was fixed is not evidence: a claimed fix you cannot see in the captures is unresolved, and a fix answered mechanically (positions moved but the named quality still absent) is partial at best. Score each prior material fix resolved, partial, or unresolved against what the captures show, and name at most three regressions the fix batch introduced. Return two sections, `verdict` and `remaining` (or "clear"), and end with the disposition recomputed against what remains open. Partial or unresolved fixes never recompute to ship, and a ship earned here covers the scored fixes, not the whole surface. diff --git a/skills/cheers-design/reference/harden.md b/skills/cheers-design/reference/harden.md index 455013a..a74284e 100644 --- a/skills/cheers-design/reference/harden.md +++ b/skills/cheers-design/reference/harden.md @@ -1,82 +1,114 @@ # Harden -Make a Cheers UI resilient to real users, real data, network failures, assistive technology, and localization. This is UX hardening first; exact Cheers mechanics live in the main `cheers` skill. +Make a Cheers UI resilient to real users, real data, failing networks, assistive technology, touch, and localization. Designs that only work with perfect data are not production-ready. This is UX hardening first; exact Cheers mechanics live in the main `cheers` skill. -## State coverage +## Visitor mode -Every interactive surface should intentionally handle: +- **Persuade + Experience:** the committed world must survive real content: long names, translated headlines, missing images, slow media, and reduced motion keep the composition intact rather than collapsing it to a template. +- **Operate + Read:** every state is part of the product. Errors, empty results, permissions, and large data use the same component vocabulary as the happy path, near the decision point. -- default -- loading and pending -- success from backend-confirmed state -- validation error -- network/server error -- empty and first-run -- permission denied and read-only -- disabled -- large data -- long text, short text, emoji, CJK, RTL -- mobile and 200% zoom +Refinement preserves: harden states and edges inside the established world, copy voice, and behavior. Do not restyle the surface while hardening it. -No optimistic UI. If the backend has not confirmed it, the UI may say "Saving..." or "Deleting...", but not "Saved" or remove the item as if deletion succeeded. +## Two isolated assessments -## Forms and decisions +When a subagent tool is available and permitted, run these independently; otherwise run them yourself in this order. -- Use visible labels, not placeholder-only labels. -- Put hints where they answer why, format, or consequences. -- Preserve user input after validation errors. -- Place field errors near fields and connect them semantically where practical. -- Use form-level errors for system or permission failures. -- Prevent risky duplicate submission with visible pending treatment and disabled or guarded controls. -- Keep destructive actions specific: name the object and consequence. +1. **Resilience assessment.** Walk the real flows and answer each question with rendered or source evidence: + - **States:** Which of default, loading, pending, backend-confirmed success, validation error, server or network error, empty and first-run, no results, permission denied, read-only, and disabled exist? Which are missing or improvised? + - **Content extremes:** What happens with 100+ character names, a single character, empty values, emoji, CJK, RTL, accents, millions and billions, 1000+ rows, 50+ options? + - **Failure:** What does the user see when the action fails, times out, is rate limited, conflicts with another edit, or the session expires? Is input preserved, and is there a way forward? + - **Concurrency:** What happens on ten rapid clicks, two tabs, or a stream that disconnects mid-update? + - **Trust:** Does anything show success, removal, completion, or a new order before the backend confirms it? + - **Access:** Can keyboard, screen reader, 200% zoom, forced colors, and touch users complete every path? + - **Gestures:** Do custom sliders, drag surfaces, and swipe rows recover from interruption and offer a non-gesture path? +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the changed pages, or check by hand when it is unavailable. Also look for fixed-width text containers, missing `min-width: 0`, placeholder-only labels, and `user-scalable=no`. -Use the `cheers` skill for exact form generation, handlers, action wiring, and tests. +Keep scan results out of the first assessment, then synthesize both before editing. -## Error handling UX +## State the resilience contract -Map outcomes to understandable states: +Before editing, list per surface: the states to cover, the backend outcome each one renders from, where each error appears, what the pending state disables, and how retry and recovery work. Name the interaction contract for each action. -- validation: field errors and preserved values -- auth expired: sign-in path or refreshed session state -- permission: explain who can act and what to do next -- not found: not-found state with navigation out -- conflict: show current backend value and recovery choice -- rate limit: say when to retry if known -- server/network: apology, retry path, support/debug reference if appropriate +## Apply -Keep errors specific, recoverable, and blame-free. Do not show raw internal errors. +Read [craft-floor.md](craft-floor.md) before editing. Implement through `cheers`. -## Deletion and undo +### Trust and pending -Use backend-modeled undo or confirmation, not optimistic removal. +- No optimistic UI. Pending may say "Saving..." or "Deleting...", disable risky repeats, and show truthful progress. It never says "Saved", removes the item, completes the step, or reorders the list before the backend confirms. +- Guard against duplicate submission with a visible pending treatment and disabled or guarded controls, so ten rapid clicks produce one action. +- Retry repeats the same backend action and shows pending again; it never reports success the server did not send. +- A stream that drops says so, reconnects or offers a way to, and never presents stale data as live. -Good options: +### Forms and validation -- soft-delete, then render a deleted or pending-deletion state with undo -- confirmation for irreversible, high-cost, or batch operations -- updated list rendered only after the backend records the change +- Visible labels, never placeholder-only. Hints answer why, format, or consequence, before submission. +- The backend validates and is the source of truth; native constraints (`required`, `maxlength`, `type`) are a courtesy that never replaces it. +- Preserve user input after errors. Field errors sit at the field and are connected semantically; system and permission failures get a form-level error. +- Don't block submission unnecessarily. +- Destructive actions name the object and consequence. -Avoid removing from the UI immediately and hoping rollback covers failure. +### Error states -## Internationalization and layout resilience +Map each outcome to a state the user understands: -- Use logical CSS properties where direction may vary. -- Avoid fixed-width text containers and fixed-width buttons. -- Let controls grow for translated labels. -- Test 30-40% longer copy. -- Use `min-width: 0` on flex/grid children that contain text. -- Use `overflow-wrap: break-word` where user-generated text can appear. -- Keep dates, numbers, units, and relative time readable for the target locale. +- **Validation:** field errors with preserved values and a suggested correction. +- **Session expired:** a sign-in path that returns the user where they were, input intact where possible. +- **Permission:** who can act and how to get access; read-only views say why. +- **Not found:** a not-found state with navigation out. +- **Conflict:** the current backend value and a recovery choice. +- **Rate limit:** when to retry, if known. +- **Server or network:** a plain apology, a retry path, and a support reference when useful. -## Accessibility resilience +Keep errors specific, recoverable, and blame-free; never show raw internal errors or codes as the message. One failing region shows its own error; never block the whole interface. -- Keyboard path reaches every control in logical order. -- Focus stays visible and moves intentionally after major changes. -- Important dynamic status is announced. -- Touch targets are large enough. -- Color is never the only meaning. -- Reduced-motion mode preserves clarity. +### Deletion and undo + +Use backend-modeled undo or confirmation, never optimistic removal with rollback: + +- soft-delete, then render a deleted or pending-deletion state with undo; +- confirmation for irreversible, high-cost, or batch operations; +- the updated list rendered only after the backend records the change. + +### Empty, loading, and large data + +- Empty states distinguish first use, no results, active filters, permissions, and failure, each with the next useful action. +- Loading names what is loading, preserves layout, and gives time expectations for long operations. +- Large data uses backend pagination, filtering, search, or chunking; never send 10,000 rows at once. + +### Text, layout, and localization + +- No fixed-width text containers or buttons; budget 30 to 40% expansion for translations. +- `min-width: 0` on flex and grid children holding text; `overflow-wrap: break-word` where user-generated text appears. Truncate or line-clamp only where the full value is reachable another way. +- Logical properties (`margin-inline-start`, `padding-inline`) and mirrored directional icons where direction may vary. +- UTF-8 everywhere. Dates, numbers, currencies, units, and relative time formatted for the locale on the server. Plurals and messages come from whole translatable strings, never concatenated fragments. +- Body and input text at least 16px on mobile (14px only for genuinely secondary text); containers grow at 200% zoom. + +### Accessibility + +- Every control is keyboard reachable in logical order, with visible focus that moves intentionally after major changes, into and back out of dialogs. Skip links on long pages. +- Important dynamic status is announced through semantic live status, not only shown. +- Color is never the only meaning; forced-colors mode keeps borders, focus, and state visible. +- Reduced motion keeps every state legible. +- Images and controls have alt text or accessible labels. +- Content and navigation are server-rendered HTML that still reads when a script fails or loads slowly; prefer normal links and forms where they suffice. +- Use feature detection, not browser detection; give unsupported CSS a fallback with `@supports`. + +### Touch and gestures + +- Touch targets at least 44x44 CSS px; nothing essential depends on hover. +- Every swipe, drag, pinch, or long-press has a visible single-tap alternative. Never disable pinch zoom. +- Interrupted gestures in custom controls, which are static JS helpers under the JS-is-exceptional guardrail: + - A second finger or pointer mid-drag: the first drag keeps its pointer or ends cleanly, never jumps. + - `pointercancel`, `lostpointercapture`, release outside the control, or window `blur` mid-drag: clear the dragging state and release capture. + - After each, the next tap or drag works without a reload. +- Static JS helpers remove their listeners, timers, and pending requests when their element is patched away or removed. +- A drag that changes data drops into a pending state; the confirmed result comes from the backend, and a failure returns the item to its confirmed place with the error. ## Verify -Walk success, validation failure, permission failure, server failure, slow network, mobile, keyboard-only, screen-reader-relevant semantics, 200% zoom, and long localized copy. +Walk every state in one batched round, desktop and mobile together: success, validation failure, permission failure, server failure, offline and throttled network, a dropped stream, rapid repeated clicks, 1000+ items, empty data, 100+ character names, emoji, RTL, CJK, 30 to 40% longer copy, keyboard only, screen-reader semantics, automated accessibility checks (such as axe) where the project runs them, forced colors, 200% zoom, and touch. For gestures, add a second finger mid-drag, scroll across the control, release outside it, switch windows mid-drag, then drag again. Fix everything in one batch and confirm with at most one more round. + +Say what produced the evidence for each check: rendered page, forced backend error, throttled network, emulated viewport, synthesized touch and which engine, or a physical device. Name what stayed untested. Add a behavioral regression test for each confirmed state or gesture fix the project's test runner can drive; use `cheers` guidance for tests and format changed templates with `cargo cheers fmt --rustfmt `. + +When edge cases are covered, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/init.md b/skills/cheers-design/reference/init.md index 21dc2c2..1c5ddb1 100644 --- a/skills/cheers-design/reference/init.md +++ b/skills/cheers-design/reference/init.md @@ -1,83 +1,110 @@ # Init -Gather project design context and write strategic docs for future Cheers UI work. Init creates the strategic base that later `shape`, `craft`, `critique`, and `polish` runs rely on. +`init` captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md: [new-work.md](new-work.md) creates or expands a world, and [document.md](document.md) records an incumbent one. -## Outputs +## Step 1: load current state -- `PRODUCT.md`: strategy, users, purpose, register, personality, anti-references, design principles, accessibility. -- `DESIGN.md`: visual system, generated by `document` when enough visual information exists or seeded when the project is new. +Look for `PRODUCT.md` at the project root (or the app root in a workspace with several apps). Update it instead of creating a competing authority. In a child app inheriting root context, confirm shared versus app-specific scope before writing. -## Step 1: inspect current context +- **No PRODUCT.md:** explore, interview, and write it. +- **PRODUCT.md exists:** ask what product knowledge is stale or missing; do not reopen confirmed fields without a reason. +- **Legacy PRODUCT.md:** add only durable missing facts. A legacy `## Register` section is superseded by per-surface visitor modes; remove it when the user agrees. +- **Only DESIGN.md exists:** leave it untouched and create PRODUCT.md. +- **Redesign or rebrand request:** preserve confirmed product truth unless the user changes it. Visual replacement happens later in new-work, not here. -Check for existing `PRODUCT.md`, `DESIGN.md`, README, docs, examples, app routes, components, CSS, and assets. Never silently overwrite existing docs. +Never silently overwrite an existing file. If another request invoked init, finish PRODUCT.md and resume it: new visual work continues in new-work, and `shape` resumes its task interview. -Infer a register hypothesis: +## Step 2: explore the project -- **brand**: landing, marketing, public docs/storytelling, portfolio, campaign. -- **product**: app shell, dashboard, settings, admin, forms, data tools. +Before asking, scan enough to avoid making the user repeat known facts: README and docs, product copy, crate and app boundaries, routes, features, workflows and roles, names, logos, legal or proof assets, brand commitments, and accessibility signals. -The register can be overridden per task later, but PRODUCT.md should record the default. +Treat repository evidence as a hypothesis, not user approval. Note visual maturity without documenting, extending, or replacing the world. -## Step 2: ask only what is missing +## Step 3: interview for product truth -Ask 2-3 questions per round and wait. Do not turn a sparse prompt into a finished PRODUCT.md without at least one user-answer round unless the repo docs fully answer everything. +Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions, require one real answer or approval round before writing a new PRODUCT.md, and confirm inferences. -Cover: +Whether anyone can answer is a mechanical test, not a judgment call: a question tool in your tool surface proves an answer mechanism exists, and a claim that the user is unattended proves nothing about this session. Probe once with the real first round. Only if that probe errors or times out, infer from the explicit brief, label every inferred fact in PRODUCT.md, and disclose the substitution in your first reply, not your last. -- register confirmation -- target users and context -- product purpose or brand promise -- desired emotional tone -- 2-3 references or anti-references -- accessibility and inclusion requirements -- strategic principles, not colors or fonts +Start with the unknowns that most change future product decisions: -Visual choices belong in DESIGN.md, not PRODUCT.md. +1. Who is the primary user, in what situation, and what job are they doing? +2. What does the product make possible, and what is its meaningfully different mechanism or position? +3. What durable constraints, assets, evidence, or product facts must future work preserve? -## Step 3: write PRODUCT.md +Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them. -Use this structure: +Do not ask for an aesthetic direction, emotional feel, visual references, colors, typography, or style during init. If the user volunteers a binding visual constraint, record it without expanding it. -```markdown -# Product +### What belongs here + +- users, jobs, workflows, purpose, success, positioning, and operating context; +- capabilities, constraints, terminology, evidence, and accessibility; +- confirmed voice, assets, and brand commitments. + +### What does not belong here -## Register +- visual worlds, palettes, typography, components, or page concepts; +- visitor mode, narrative, CTA or proof sequence, or other surface strategy (that goes in surface briefs); +- invented testimonials, customers, benchmarks, pricing, licensing, or deployment claims; +- a requirement to decide every optional field. -product +## Step 4: write PRODUCT.md + +Write only confirmed facts and explicitly marked open decisions. Omit irrelevant sections rather than filling them with generic prose. + +```markdown +# Product ## Users -[Who they are, context, job to be done.] +[Primary users, their situation, and job. Add other audiences only when confirmed.] ## Product Purpose -[What this does, why it exists, what success looks like.] +[What the product does, why it exists, and what success means.] -## Brand Personality +## Positioning -[Voice, tone, emotional goals, 3 concrete personality words.] +[The product mechanism or claim a neighboring product could not truthfully copy.] -## Anti-references +## Operating Context -[Specific patterns, products, or aesthetics to avoid.] +[Workflows, environments, tools, documents, materials, and rituals that are factual parts of using or evaluating the product.] -## Design Principles +## Capabilities and Constraints -[3-5 strategic principles.] +[Confirmed functionality, technical constraints, terminology, and explicitly undecided product facts.] + +## Brand Commitments + +[Existing name, voice, assets, personality, identity constraints, and references the user explicitly made binding. Omit when none exist.] + +## Evidence on Hand + +[Real content, data, demonstrations, testimonials, case studies, press, or assets, with paths where applicable. State absences that future work must not fabricate.] + +## Product Principles + +[Three to five durable strategic principles derived from confirmed answers; no visual recipes.] ## Accessibility & Inclusion -[WCAG target, reduced motion, color, keyboard, assistive tech, language needs.] +[Known user needs or required standard. Omit when no product-specific requirement was established.] ``` -The register value should be exactly `product` or `brand`. +Preserve useful legacy headings. Write the file before any visual-world or surface-concept work. + +**Completion gate:** before loading new-work or resuming shape, verify that PRODUCT.md exists and contains the confirmed product record. Interview notes or later design prose are not a substitute for the file. -## Step 4: offer DESIGN.md +## Step 5: wrap up or resume -If UI code exists, offer to run `document` in scan mode. If the project is new, offer seed mode. Do not write DESIGN.md unless the user agrees or explicitly asked for it. +Summarize captured and deliberately undecided facts. Do not offer DESIGN.md merely because it is missing. -When writing or refreshing DESIGN.md, use the Google Stitch-compatible frontmatter and section shape described in `document.md`. +Recommend the next action from the actual project state: -## Step 5: wrap up +- Empty or early project: ask for the surface to be built, or suggest `cheers-design shape ` when the user wants a confirmed brief without implementation. New-work establishes a visual world only when the requested work needs one. +- Existing coherent interface without DESIGN.md: `cheers-design document` if the user wants the incumbent system recorded independently of a new build. +- Existing surface needing work: name the most relevant scoped command. -Summarize what was written and the principles that future `cheers-design` commands should follow. If this init flow was a blocker for `craft`, resume into `shape`; init context is not a task-specific brief. +If init was invoked by another request, resume it. diff --git a/skills/cheers-design/reference/layout.md b/skills/cheers-design/reference/layout.md index 727c2b6..18adc8a 100644 --- a/skills/cheers-design/reference/layout.md +++ b/skills/cheers-design/reference/layout.md @@ -1,62 +1,77 @@ # Layout -Fix spacing, rhythm, hierarchy, and responsive structure in a Cheers UI. Layout problems are usually structural, not cosmetic. +Layout turns product priority into reading order, grouping, rhythm, and usable space. Diagnose the structural problem before moving boxes. -## Register +## Visitor mode -- **Product**: predictable grids, consistent density, familiar navigation, structural responsive changes. -- **Brand**: stronger composition, asymmetric or strict editorial grids, fluid spacing, deliberate pacing. +- **Persuade + Experience:** composition may be asymmetric, fluid, or intentionally disruptive when the selected world earns it. Change composition and pacing per breakpoint, not just size. +- **Operate + Read:** predictable structure, stable density, and navigable linearity are affordances. See [operate.md](operate.md#layout). -## Assess +Preserve the established visual world. A layout command changes structure inside it; identity replacement belongs to [new-work.md](new-work.md) and DESIGN.md. -Check: +## Two isolated assessments -- Is the primary action obvious in two seconds? -- Are related elements close and unrelated groups separated? -- Is every section/card using the same padding and rhythm? -- Are there nested cards or wrappers without purpose? -- Does the layout adapt on mobile, or only shrink? -- Are tables, forms, and toolbars using familiar patterns? -- Do update regions align with meaningful visual sections? +When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let scan findings anchor the design assessment. -## Improve +1. **Layout assessment.** Inspect representative states and viewports. Answer every question with rendered or source evidence (a file, selector, or computed value): + - **Reading order:** apply the squint test. With detail blurred, can you still find the primary element, the secondary element, and the major groups, in order? Is the primary action obvious within two seconds? + - **Grouping:** are related items close and distinct groups separated, or are containers compensating for weak proximity? + - **Rhythm:** do tight and generous intervals create a deliberate cadence, or is one spacing value repeated until everything has equal weight? + - **Structure:** does the topology match the content and task? Are repeated cards, columns, or sections genuinely equivalent, or a default? + - **Density:** does the information per region fit use frequency, decision complexity, and visitor mode? + - **Adaptation:** at narrow, intermediate, wide, zoomed, and localized states, what reorders, collapses, wraps, scrolls, or stays fixed? Do DOM and focus order still agree with the visual order? + - **Update regions:** do the regions the backend patches line up with meaningful visual sections? Does a patch, a validation error, or a pending state shift the surrounding structure? + - **Extremes:** do long content, empty states, overlays, sticky elements, safe areas, and small touch targets expose structural failures? +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) with the layout scope, for example `impeccable detect --json --scope layout `, adding `--viewport 390x844` for mobile. Also inspect arbitrary spacing, overflow, stacking, and container behavior it cannot resolve, including values set in `html!` templates. -### Establish spacing +Synthesize both before editing. A clean scan cannot prove hierarchy or rhythm. -Use existing CSS variables or introduce a small semantic local scale only when the project lacks one. Use `gap` for sibling spacing. Use margins for relationships between independent blocks. Avoid arbitrary one-off values unless the optical adjustment is intentional. +## Set the spatial thesis -### Choose the right structure +Before editing, name: -- Flexbox for rows, toolbars, button groups, and component internals. -- Grid for page regions, dashboards, responsive card/list arrangements, and coordinated columns. -- Container queries when a component must adapt to its parent, not the viewport. -- `min-width: 0` on flex/grid children containing text. +- the primary reading or task path; +- what belongs together and what must separate; +- which element leads and which supports; +- the intended density and spacing rhythm; +- how the structure changes across containers, viewports, input modes, and content extremes. -### Reduce container noise +Choose the simplest structural model that expresses those relationships. -Do not wrap everything in cards. Use cards only for distinct objects or actionable groups. Never nest cards inside cards. Use headings, spacing, dividers, and background layers for hierarchy. +## Apply -### Responsive behavior +Read [craft-floor.md](craft-floor.md) before the first edit; its spacing checks and its refusals (card scaffolds, nested cards, hero-metric template, side stripes) apply here and are not repeated. -- Product: collapse sidebars, stack form columns, transform tables into appropriate compact views, keep primary actions reachable. -- Brand: change composition and pacing per breakpoint, not just font size. -- All touch targets should be large enough and not hover-only. +- Group by meaning. Use proximity before adding containers, borders, or decoration; use headings, spacing, dividers, and background layers for hierarchy. +- Create rhythm through deliberate contrast between tight and generous intervals. +- Use the project's documented spacing scale. When none exists, introduce a small semantic one (`--space-xs` through `--space-xl`) on a 4-unit base, which gives the middle steps an 8-only scale misses. Avoid one-off values unless the optical correction is deliberate. +- Let hierarchy follow product priority, not framework or template defaults. Do not center everything by reflex. +- Pick primitives by the relationship they control: flexbox for rows, toolbars, button groups, and component internals; grid for page regions, dashboards, and coordinated columns; container queries when a component must adapt to its parent rather than the viewport. Put `min-width: 0` on flex and grid children that hold text. +- Use `gap` for sibling rhythm; margins for relationships between independent blocks. +- Make responsive behavior structural: reorder, collapse sidebars, stack form columns, give tables a compact view, and keep primary actions reachable. Never hide core functionality on mobile. +- Give touch targets a usable hit area (about 44px) even when the visible mark is smaller, and never make an action hover-only. +- Use depth only when it clarifies state or hierarchy, and stack with a semantic z-index scale, not arbitrary values. +- Make optical corrections only after inspecting the rendered result. -## Cheers fit +Variation is not a goal by itself. Repetition supports recognition; break it only when content or priority changes. -- Extract repeated structural chunks only when it improves clarity and reuse. -- Keep meaningful update regions stable and visually coherent. -- Follow project CSS conventions. -- Use `cheers` for exact component and patch mechanics. +### Cheers fit -## Never - -- Use side-stripe card accents. -- Use identical icon-card grids as the default answer. -- Center everything by reflex. -- Use arbitrary z-index values instead of a semantic scale. -- Hide core functionality on mobile. +- Keep backend update regions stable and visually coherent: a patched region keeps its footprint, and pending or error states reserve their space instead of pushing the page around. +- Extract a repeated structural chunk into a component only when it improves clarity and reuse. +- Follow the project's CSS conventions; use `cheers` for component and patch mechanics. Format changed templates with `cargo cheers fmt --rustfmt `. ## Verify -Run the squint test, keyboard through the page, check mobile/tablet/desktop, and inspect long text. If the structure lands but details still feel unfinished, run `polish`. +Inspect in one batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, then rerun the scan once. Answer each item with rendered or source evidence; a bare "yes" is not verification. + +- The squint test still reveals the primary, secondary, and major groups in order. +- The reading and task path stays clear at every supported size. +- Related content groups naturally; unrelated content does not blur together. +- Tight and generous spacing make an intentional rhythm, not monotony. +- Density matches use frequency and content complexity. +- Long text, empty states, localization, zoom, and backend-patched content do not break the structure. +- Keyboard, touch, and assistive-technology order agree with the visual order. +- The final scan has no unexplained findings. + +When the structure holds, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/modes.md b/skills/cheers-design/reference/modes.md new file mode 100644 index 0000000..19ef5f9 --- /dev/null +++ b/skills/cheers-design/reference/modes.md @@ -0,0 +1,81 @@ +# Visitor mode rules + +How far a visual world may reach into a surface depends on its visitor mode. These rules govern every direction, composition, and mock for the surface; where they conflict with shared guidance, they win. Read the section for the surface's mode before writing directions in [new-work.md](new-work.md). + +## Persuade and Experience + +On these surfaces the design is what the visitor judges, so the world may own and structure the page. + +### Directions + +When the chosen world's source is itself an interface language, the surface may carry its native grammar across navigation, content, controls, and states. + +For **Persuade**, the opening must make the offer intelligible and desirable, expose a clear action, and demonstrate something only this product can prove. The action is the one the category's visitors came to take, in its working form: an airline's route-and-dates search, a clinic's open appointment slots, a store's add to cart. A decorative link pointing at it elsewhere does not count. Conversion lives inside the form's own vocabulary: a hook that lands in one line, a visible primary action, a legible reading order. A committed form that hides the offer or the action has not finished translating. + +For **Experience**, the work itself leads from the first viewport. + +### Composition + +The world may be the carrier of the page, never a picture of it: a facade, a shutter, or a book can be what the page is built on, while a viewport painted whole as a facade, book cover, or travel poster with no working parts is a picture of the world, not its website. Material coverage is wanted: the world's material is the ground and the major surfaces, its type sets the headlines. A world reduced to an accent on a neutral template is the category default with a sticker on it. Coverage is not performance: one dominant move acts out the concept, and the rest stays in the world's material without performing it. + +Both ends erase the direction: the painted poster, and the generic product page (a headline over subcopy and a button, a row of equal cards below). A split hero (copy on one side, the product on the other, a badge row under it) or a centered headline over a row of cards is the template whatever world paints it. + +The world carries the page's parts and never absorbs them: navigation set into a facade reads as links, copy on a shutter reads as set text, an action on a door plaque is plainly clickable, text reads against whatever sits behind it, sections keep a steady vertical rhythm, the primary action is unmistakable, and the section below starts as a section rather than more painting. Fix a poster by making its parts work where the world put them, never by moving them into a standard layout on the world's color. + +When the world is an object, the page is that one object seen once, at one scale and from one point of view, and the object keeps its real form: a book opens to two pages on one gutter, never a third panel, and a spine that carries the navigation belongs to the book on the page, never a second book beside it. More content goes on the object's own surfaces or on the next spread below, never on extra copies or impossible folds. + +Alternates each go further than the lead, never cleaner: a bolder use of the same world, a larger or stranger focal move, or a composition the category would not attempt. + +### Depth + +- **Type.** Write three concrete voice words with physical qualities (warm, mechanical, ceremonial, clinical, restless, tactile), never "modern" or "clean". Name the faces you would reach for by reflex and treat them as spent. Choose type like an object from the subject's world: museum caption, terminal manual, fabric label, concert poster, receipt, field guide. Fluid display sizing and strong scale contrast are available when the composition earns them. Light text on dark grounds needs more line height, a touch more tracking, and often one step more weight. +- **Color.** Committed, Full palette, and Drenched are available; do not hedge once chosen. Palette is voice: a calm brand and a restless one should not share palette mechanics. Name a real reference before picking values. If a cultural-symbol palette is obvious, reach past it and let type, imagery, and copy carry the cultural signal. +- **Layout.** Centered stacks are a default, not a concept. Asymmetry, strict visible grids, oversized type, and single-purpose sections are available when they match the world. Vary rhythm: the page can breathe, compress, pause, and accelerate. +- **Imagery.** Image-led subjects need imagery: restaurants, hotels, travel, fashion, products, communities, places. Use real project assets first; one decisive image beats five mediocre ones. Imagery can also be product screenshots, data visualization, authored SVG, canvas, or WebGL when that is the world. Alt text is part of the voice. +- **Motion.** Larger reveals, scroll moments, and typographic choreography are available, still with purpose, performance budgets, and reduced-motion alternatives. One memorable motion idea beats scattered micro-interactions. + +## Operate + +On an Operate surface the visitor came to get a job done, so the page is first a working product of its category and the world serves it. + +### Directions + +Someone who uses tools like this one should know where everything is before they notice the world. The world lends four things and only these: type, palette, density, and one signature move. It never supplies the layout, the navigation model, or the controls. Color does real jobs: a committed palette for the shell (a colored rail or header, a tinted ground), state colors, data series, selection, and the signature move. A gray screen with one accent color is the category default without the category's polish, not restraint. + +A world taken from a tool or instrument the audience operates (a terminal, a scope, a control panel, a cockpit) or from a fictional interface comes back as a costume of that tool on a working screen: take from it only what transfers as type, palette, density, and a signature move, or replace it. Read every candidate and challenger through that limit before you fuse or judge it. + +Write each direction's first viewport as the product's shell first: the navigation, the work areas and what each is for, the data the visitor reads first and its states, and then where the signature move lives. Expression may never obscure the task, state, or familiar affordance. Name the signature move concretely: service health drawn as a transit map, a schedule set in a timetable's column rhythm. A direction whose world shows up only as a color scheme has not found its move yet. When you weigh challengers, product clarity includes reading as a working product of this category. + +### Composition + +The screen sits in the direction's committed palette: its shell and navigation with a distinct area for each job and, where there is data, filters over what they scope and charts and tables with clear states. Every control is a standard web control the visitor already knows: buttons, tabs, inputs, selects, filters, tables with sortable headers, navigation that reads as navigation. Never a costume of the world's own interface: a terminal's function-key bar, an instrument's bezel, ruled ledger paper standing in for a table. A screen an engineer could not build from standard web components is a picture of the tool, not the tool. The finish bar is the best product in the category: an aligned grid, consistent spacing, a real type scale, and clear hierarchy. The signature move adds to a screen that is already that clean; it never stands in for it. + +Use the screen's real content: the product name, realistic data with plausible values and units, real labels, and one state worth seeing (an alert, a degraded service, an empty filter result), never placeholder tiles. + +Alternates vary the product's organisation, never its world coverage: the navigation model (side rail, top bar, command-first), how the work areas divide the screen, which data leads, the density, and where the signature move sits. Each must be recognizably different from the lead at thumbnail size; an alternate only its description can tell apart adds no choice. An alternate that adds world material, texture, or ornament goes further in the wrong direction. + +Self-check: with the name covered, does it read as a product of its category, could the visitor do the task from it, and is it at least as clean as the category standard and more distinctive than it? If it reads as an artifact of the world first, rework it with the shell and work areas named region by region and the world held to its four contributions. + +Depth for Operate surfaces lives in [operate.md](operate.md). + +## Read + +On a Read surface the visitor came to understand something, so the page is first a document of its kind, framed by the world. + +### Directions + +The reader's question leads, and comprehension and wayfinding stay intact at every step. Documentation reads as documentation, a guide as a guide, an article as an article, a changelog as a changelog. The world owns the frame and serves the column. The frame is the masthead, the navigation rail, the ground, the title and section openers, and the way code, tables, and callouts are set: there the world's palette, type, and signature move commit fully. The reading column inside it stays calm: a reading face, real contrast, a real measure, nothing performing behind the text. The world never supplies the reading order or replaces the navigation with something a reader has to learn. + +Candidates from the world's own publishing traditions transfer best: reference books, type specimens, timetables, field guides, technical manuals, scholarly apparatus, a newspaper's wayfinding. Tools and fictional interfaces from the audience's world come back as costumes; take only type, palette, density, and a signature move from them. + +Write each direction's first viewport as the document's shell first: the navigation and where the reader stands in it, the title and the opening that answers or frames the question, the reading column, and the way forward (contents, section headings, next and previous). Then name where the world owns the frame and where the signature move lives: a masthead, a colored rail, a running head, a margin system, a numbering scheme, a way of setting code or tables. When you weigh challengers, product clarity includes how fast a reader finds and understands the answer. + +### Composition + +A frame the world owns, in the direction's palette and type, around a calm reading column at a real measure (65–75 characters, body near 16px), with headings in a clear hierarchy and wayfinding that carries the reader through. Body text is set in a reading face; monospace is for code, parameters, and small labels, never running text or headings by default. Code, tables, notes, and figures sit in the forms readers already know, set in the world's type and palette. The signature move is one system used where it earns its place, never a frame repeated around every element. + +Use the real material: the actual title, a real opening paragraph, real section names, and one example of the hardest content the surface holds (a code sample, a reference table, a diagram). + +Alternates vary the reading structure and how the frame carries the world, never the column: the navigation model (sidebar tree, top tabs, inline contents), the column and margin system, reference density, and where the signature move appears. Each must be recognizably different from the lead at thumbnail size. Pushing world material into the reading column goes the wrong way. + +Self-check: can a reader tell where they are and where to go next, and read the body comfortably? Then cover the name: could this be any other product's documentation? If so, push the frame further into the world. If it reads as an artifact of the world before it reads as a document, pull the world back to the frame. diff --git a/skills/cheers-design/reference/new-work.md b/skills/cheers-design/reference/new-work.md new file mode 100644 index 0000000..47cd08a --- /dev/null +++ b/skills/cheers-design/reference/new-work.md @@ -0,0 +1,139 @@ +# New visual work + +Use this flow for a new surface or a replacement visual identity. PRODUCT.md owns product truth. DESIGN.md owns durable visual decisions. A surface brief keeps strategy that belongs to one route or artifact. Complete [init.md](init.md) first when PRODUCT.md is missing; a missing DESIGN.md does not route back to init. + +## 1. Decide what is already true + +Read DESIGN.md, representative templates, CSS, tokens, components, and assets, and look at the running app when it is available. + +- **Redesign:** preserve product truth, content, function, constraints, and explicit brand commitments; replace the old visual world rather than polishing it. The old look is evidence of what the subject is, not authority over what it becomes. +- **Established world:** inherit it. A missing DESIGN.md does not erase a coherent identity already in code; document that identity instead of inventing a replacement. +- **Incomplete brand:** preserve confirmed assets and recognizable traits, then expand the system with the user for this surface. +- **No visual authority:** create a new world with the user. + +A section, component, feature, or state inside an established surface inherits that surface. Never turn a local addition into a new identity exercise. + +## 2. Ask what will change the work + +Before implementation, get the user's answer through the structured question tool when available; otherwise ask and wait. Ask two or three related questions; a precise request needs only a compact confirmation. Skip settled facts, not the confirmation: DESIGN.md settles the visual world, not this surface's purpose or concept. + +- **Persuade:** who must act, what they should believe, which real proof, content, or assets earn that belief. +- **Operate:** the task, information, important states, frequency, constraints. +- **Read:** the reader's question, source material, structure, wayfinding. +- **Experience:** what leads, how exploration unfolds, which interaction or transition matters. + +Across modes, ask what success looks like, what must remain untouched, and what would make a polished result feel wrong. Never ask for CSS values or canned aesthetic lanes. + +If a confirmed [shape](shape.md) brief already answers these, use it instead of asking again. + +## 3. Choose the right amount of invention + +### Extend an existing surface + +Inherit its world and composition. Resolve only the new purpose, content, hierarchy, states, interaction, and how the addition joins the surrounding experience. No direction round, and no DESIGN.md change unless the user approves a durable system change. + +### Create a whole surface inside an established world + +Keep the visual system fixed. Derive five to seven materially different structures from the content, task, and user behavior, ordered by resonance. Present three as options of equal weight, and make at least one of them come from the lower half of your list: your top-ranked structures are where every run in this category lands. Every option visualizes composition, not identity, because the world is settled. The user picks one, steers, or asks for a fresh three. Skip this round for a local extension or a precisely specified narrow request. + +### Create or replace the visual world + +1. Name the product's unique mechanism in one sentence, the audience's real scene, its cultural home, and what this first surface must prove. Note the page this category always ships and its predictable opposite; both are the rut and stay off the candidate list. A brief that paints its own picture (a product name, a titled artifact, a governing metaphor) adds its literal reading to the rut: spend at most one candidate on it. +2. From that cultural world, list seven concrete visual systems, artifacts, places, or rituals the audience knows by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. The audience's world includes its graphic and screen traditions: the notation, publications, identity programs, data graphics, and interfaces it reads daily. On an Operate or Read surface, candidates never come from the tools and instruments the audience operates; a terminal or control panel handed to a working screen comes back as a costume. On a Persuade or Experience surface, also ask what this thing would look like as a physical object and what its world looked like before the web. Near-duplicates count once. When more than three of the seven share one material family, dig until the list spans at least three families. +3. Turn that material into complete directions: each joins a reusable visual world to a concrete first-surface experience, under the mode's rules in [modes.md](modes.md). +4. Break the ranking rut. Your top-ranked candidate is often where most runs in this category land, so it never leads by default. Lead with the strongest viable candidate from positions two to four of your list. Then deal two challengers: the most distant viable candidate from your list, and one foreign form, a working system from outside the audience's world (another culture's graphic tradition, another discipline's notation, an industry the category never borrows from) that can still carry the mechanism. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, clarity wins conflicts. Weigh each fused challenger against the lead on exactly two axes, audience identification and product clarity, as [modes.md](modes.md) defines clarity for this mode. Decide each verdict before any borrowing: **wins** (beats the lead on both; becomes the lead), **competitive** (holds one axis; stays a full alternate), or **declined** (loses both). Losing to strong grounded material is a valid outcome; beating a thin or one-family list is the point. A declined challenger still donates: name the one discipline of its system the lead lacks (a palette's total commitment, a grid's density courage, a form's structural honesty) and raise the lead to match, written as its own line naming the donor. Donations transfer ambition and discipline, never the challenger's clothes; a lifted motif is a costume note, not a raise, and one world owns the page. +5. Present one direction, fully committed and already raised: world, first viewport, visitor path, signature interaction, cross-surface reach, honest risk. Add winning or competitive challengers as full alternates (at most three) and declined ones as one-line notes with their verdict and what the lead kept from them. When your top-ranked candidate is not the lead, add it as one more option, labeled as your pick, with an honest risk line naming its familiarity when true: familiar and effective is a legitimate destination, and the user deciding that trade is the point of showing it. One pick, never a ranked list, and never in the lead position. Through the structured question tool, the option list carries the lead, the pick, the winning and competitive challengers, and the standing exit last; declined challengers fold into the lead's description as their kept lines. +6. Offer a re-roll with an optional one-line steer in three registers: plain (a fresh hand, same spread), safer (your remaining conventional grounded candidates, plus the category standard against named competitors), or bolder (foreign forms only, at full commitment). The register is the user's steering, never yours to pre-select. "Bolder" or "safer" said while a direction round is open means these registers, never the `bolder` or `harden` commands. + +**The standing exit.** Every direction round offers one quiet, permanent alternative: the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the other directions, and never let it soften them. When the user takes it (the standing-exit option, a safer steer that lands there, or plain words asking for the familiar or competitor-like path), convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the convention at full fidelity, without irony or smuggled quirk. The anti-default checks in section 4 bind the unchosen default, not a chosen one. Record a standing preference as a brand commitment in PRODUCT.md. + +A re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. Re-roll on your own only on named factual grounds, when a direction cannot carry the product's truth or task; taste is never grounds. A user- or brief-pinned direction beats the round, always. Resolve collisions field by field: preserve every pinned constraint; in dimensions the brief leaves open, the chosen direction still binds through its topology, controls, state vocabulary, and ritual; when only its materials conflict with a pinned visual direction or a PRODUCT.md brand commitment, translate that material expression and name the translation. A look mismatch is not grounds to re-roll. + +Every direction you present must already be viable: every relationship and claim it shows true, a real palette and component family, one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace. Prices, customers, benchmarks, endpoints, and capabilities the product does not have stay uninventable. Refusing a bold direction because its demonstration data does not exist yet is timidity wearing honesty's clothes. + +If the harness can generate images and the user wants it, a mock of the chosen direction's first viewport may calibrate ambition before code. It is a reference for finish and commitment, not a pixel contract. Without one, the ambition lives in the direction contract's FIRST VIEWPORT block and signature interaction. + +## 4. Commit the world + +Pick a color strategy before picking colors: Restrained (neutrals tinted from the world plus one accent; common on screens people operate or read, where color still does real jobs), Committed (one saturated color carries 30–60% of the surface), Full palette (3–4 named roles), or Drenched (the surface is the color). Persuade and Experience surfaces have permission for the bolder strategies; take them when the brief allows. Color commits at page scale: fields that own whole regions, not accents scattered over a neutral ground. Dark or light is never a default: write one sentence of physical scene (who uses this, where, under what light) and let it force the answer. + +Choose faces like objects from the subject's world, in the mode's register. Operate and Read surfaces are well served by system stacks and workhorse UI faces. Persuade and Experience surfaces want faces with a point of view, and these training-data defaults mean you stopped looking: Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter-as-display, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans. Naming one anyway requires a reason no other face could satisfy, and a subject association is never that reason: books wanting a serif and tech wanting a mono are the associations the list exists to break. + +Calibration: generated interfaces cluster around a few looks regardless of subject: warm cream ground, high-contrast serif display, and a terracotta or signal-red accent; near-black with one neon accent and glowing edges; broadsheet-editorial hairlines, italic display serif, and small tracked mono labels. All are legitimate when the brief calls for them. Where the brief leaves the aesthetic free, landing in one means the self-check failed: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework it. + +- Energy is not the enemy of trust. A brief's negative constraints (no gamification, no hype) rule out those devices, not exuberance, and adjectives describing the product's behavior (quiet support, calm coaching) do not dictate the surface's energy. +- Your rendition prior: warm, bookish, family, and child-facing subjects come out as cream grounds, italic serif display, and lamplight even when the direction never asked for them. Treat that first palette as already spent. Before writing code, reread the OWN-WORLD block: when it says cream, paper, parchment, ivory, or lamplight on a Persuade surface the brief did not pin, rework it from the world's saturated materials first. Book cloth, thread, jackets, and endpapers span the whole saturated spectrum; cream paper is its smallest corner. +- A brief-pinned world pins the world, not its softest rendition. Its full material range stays in play. + +## 5. Record the decision + +Before code, record the chosen direction under `## Direction contract` in the surface brief. Surface briefs live at `.cheers-design/surfaces/.md`; compute the slug from the primary target's source path with `node /scripts/critique-storage.mjs slug ""`. Read an existing brief before updating it. + +Use six short blocks, roughly 150 words total: + +- **THESIS:** the one idea this surface owns and the category-default arrangement it refuses. +- **OWN-WORLD:** the palette and component language, specific enough to be recognizable with all content removed. +- **STORY:** what the visitor understands, believes, and does. +- **FIRST VIEWPORT:** the exact composition, what is where and at what scale, and where the primary action sits. +- **FORM:** the chosen form, its position on your ordered list, the signature interaction, and the motion grammar. +- **FINISH:** verbatim "unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md". + +If a block reads like a mood, the direction is not decided yet. Keep the rest of the brief small: scope and visitor mode; audience, job, action or task, proof or content, constraints; memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it. Re-read the brief after writing and confirm all six blocks are present. + +Never copy the direction contract into Rust source, templates, CSS, or anything delivered to the browser: no rendered comments, hidden DOM, `data-*` attributes, metadata, or accessibility-only text. Reviewers and documenters receive it from the surface brief. + +On a new or replacement world, DESIGN.md is written at finish from the built world (section 7); a rulebook written before the build gets defended against reality instead of describing it. An ordinary extension does not rewrite DESIGN.md. + +For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation. + +## 6. Build with full commitment + +Build the chosen direction, not a safer interpretation of it. The form supplies structure, reading order, component conventions, and native motion; the product supplies every fact. Commit every atom: nav, buttons, inputs, and links are rebuilt in the form's vocabulary, and a stock component inside a committed form is a lapse. Land the first build fully committed; the passes that follow make it clear and effective, never diluted. + +1. **Structure before details.** Plan in design terms: landmarks and heading hierarchy, content groups and reading order, primary, secondary, and tertiary actions, form, table, list, detail, empty, and error patterns, refreshable regions as conceptual boundaries, and the mobile structure (not a squeezed desktop). Build semantic shape first; never begin by styling a pile of divs. +2. **Implement through `cheers`.** Use it for `Render`, generated helpers, Datastar attributes, actions, patches, streams, tests, and formatting. From this skill, keep interaction honest and backend-confirmed, pending feedback visible without implying success, local affordances local, state and errors near the decision point, components extracted when they clarify repeated UI, and CSS in the project's conventions and token vocabulary. +3. **Apply the craft floor.** [craft-floor.md](craft-floor.md) is loaded by now; build to it without announcing it. + +Across the build: + +- **The first viewport is a thesis, not a header.** Demonstrate the mechanism immediately, at the scale the form has in life; do not trap the concept inside a standard hero or card shell. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood, the concept has not committed yet. +- **Prove, don't claim.** Show the subject doing its job: the interface at work, the mechanism dramatized, specifics a competitor could not copy-paste. +- **Author the assets; never substitute chrome.** Great surfaces live on carefully made content: names, entries, copy, covers, thumbnails, textures. Every blank the ask round left open is yours to author at production fidelity. Gradients, glass, generic icon tiles, and many-vertex `clip-path` polygons where an authored asset belongs are the gap wearing chrome. +- **Build the form's web leverage.** When the chosen world names a technique (canvas, WebGL, view transitions, generative motion), build the technique itself, not a static imitation, within the JS-is-exceptional guardrail. +- **Pace the scroll like a studio.** Vary density, scale, image, motion, and quiet inside one grammar; a dense passage earns a quiet one, and the page ends anchored by a real close. +- **Use real, verified imagery when the brief implies it.** Search for the subject's physical object rather than the category; verify stock URLs resolve. +- **Author motion as material.** Give the page the form's native motion once, orchestrated, rather than scattered hover effects. Bound expensive effects and keep content visible by default. + +Preserve semantics, accessibility, performance, responsiveness, project conventions, and working behavior. + +## 7. Inspect and finish + +Inspect in one batched round: desktop (1440 wide) and mobile (390 wide) captures of the running app, through browser automation when available. Headless Chromium (`chromium --headless --screenshot= --window-size=1440,900 `) is a fallback that captures only the window, so raise the window height to cover the page. Add the user's actual viewport when known. Settle or disable entrance motion first, capture full pages from the document top, then open every capture once and confirm it shows what its name claims: no blank regions, no wrong section, no half-loaded state. Save them as `desktop.png` and `mobile.png` in `.cheers-design/review//`, one directory per changed page, using the same slug helper as surface briefs. Clear stale captures from that directory before capturing. + +Critique the render against the request and the direction contract, fix material gaps in one batch, and confirm with one final round. Two rounds is the ceiling; after the second, the build thread's polishing is over, and whatever remains goes through the reviewer, where fresh context finds it better. Do not invent defects to show iteration. Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) once over the changed pages, fix what is mechanical, and pass the rest to the reviewer. On a Persuade surface, confirm a first-time visitor knows what this is, why it matters, and what to do within seconds. + +Then hand off to a fresh reviewer. When the harness can spawn subagents, spawn one with no inherited conversation and have it follow [finish-review.md](finish-review.md), passing the original request, confirmed answers, the changed files, the capture paths, the surface brief path, the PRODUCT.md path, any scan findings, and the craft-floor path. A reviewer that inherits your transcript inherits your optimism. If an approved image mock exists, pass it as a critique reference: provocation about what it dared, not a spec. Check the return carries the disposition line and its contracted sections; on an empty or thrashed return, respawn once with the same inputs. Without subagents, step fully out of the build context, run finish-review.md yourself, write its full output before acting on it, and disclose the substitution in one line at the end. + +Act on the reviewer's disposition: + +- **recapture:** the evidence failed, not the build. Recapture what it names and run a full review again. +- **rebuild:** fidelity failed wholesale. Skip the fix batch: re-derive the named regions, produce the named assets, and send the result for a fresh full review, never a verdict pass. Tell the user what is happening; consult them only on a second rebuild or when rebuilding would discard content they approved. +- **fix:** apply the material fixes in one batch, recapture the same files, and send them back to the same reviewer (by continuation when the harness supports it, otherwise a fresh subagent running finish-review.md's Verdict pass) to score each fix resolved, partial, or unresolved. Partial or unresolved fixes get another batch, recapture, and verdict. Two rounds is the unattended budget; in an attended session, when the second verdict still lists open items, put the table in front of the user and let them choose between shipping as it stands and funding another round. Stop the moment a round resolves nothing. Work only from the reviewer's list, never your own re-opened hunt. +- **ship:** nothing is owed. + +Report the verdict under the reviewer's own word and at its actual scope. A verdict pass that scored three fixes resolved supports "all three fixes resolved", not "no issues remain". When the user answers a ship with contrary evidence, that evidence outranks your captures: start a fresh full review with it. + +After the last correction, record the world. New worlds and approved system changes require a token-bearing DESIGN.md written from the build per [document.md](document.md), preferably by a fresh subagent given the project root, changed files, direction contract, PRODUCT.md, and document.md. Never canonize a craft-floor refusal into DESIGN.md; note it as a defect the build carries. Ordinary extensions compare the finished build against the incumbent system, preserve its files, and report pre-existing drift without repairing it unasked. + +Once review and documentation are complete, append `FINISHED: ` under the direction contract in the surface brief. A brief without that line is an unfinished build. + +## Present + +Summarize: + +- files changed and the surface brief path +- the direction chosen and how the build keeps its promises +- interaction contract used and states covered +- viewports inspected, scan result, and the reviewer's disposition +- formatting, tests, and checks run through `cheers` guidance +- synthetic material to replace, remaining limitations, and follow-up risks diff --git a/skills/cheers-design/reference/onboard.md b/skills/cheers-design/reference/onboard.md index 904b605..d95c2f0 100644 --- a/skills/cheers-design/reference/onboard.md +++ b/skills/cheers-design/reference/onboard.md @@ -1,63 +1,94 @@ # Onboard -Design first-run, empty, help, and activation flows that get users to value quickly in a Cheers app. +Design first-run, empty, help, and activation flows that get users to value quickly in a Cheers app. Onboarding's job is not to teach the product; it is to reach the moment that proves the product is worth the user's time. -## Principle +## Visitor mode -Onboarding should get users to their first useful outcome, not teach the whole product. Use real product surfaces and backend-confirmed actions where possible. +- **Persuade and Experience:** a welcome or activation moment may carry the committed world at full strength, as long as the next action stays obvious and working. +- **Operate and Read:** onboarding lives inside the real product surfaces. Familiar affordances, stable layout, and the task outrank ceremony. -## Discover +Preserve the established visual world, copy, and behavior outside the flow. Identity replacement belongs to [new-work.md](new-work.md). -Ask or infer: +## Two isolated assessments -- What is the aha moment? -- What does a new user need before reaching it? -- What can be skipped by experienced users? -- Which empty states are common? -- What sample data, templates, or defaults can the backend provide? -- What fears or trust gaps appear before the first action? +Run these independently when a subagent is available; otherwise run them in this order. -## Patterns +1. **Design assessment:** answer each with rendered or source evidence: + - What is the aha moment, and how many steps stand between a new user and it? + - Who arrives: experience level, motivation, time available, what they came from? + - Where do users stall, drop off, or meet a blank screen? + - Which empty states occur (first use, user cleared, no results, no permission, failed load), and does each say what goes here, why it matters, and what to do? + - What can experienced users skip, and is the skip visible? + - What sample data, templates, or defaults can the backend provide? What trust gaps appear before the first action? +2. **Mechanical scan:** run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the first-run and empty-state pages. Keep its results out of the first assessment, then synthesize both before editing. + +## State the flow before editing + +Name the aha moment, the minimum a user must learn to reach it, the first action, what is skippable, and which steps or progress markers depend on backend state. When the product tracks it, name the success signal: completion, skip, drop-off, or time to value. Then read [craft-floor.md](craft-floor.md). + +## Apply + +### Principles + +- **Show, don't tell.** Use real product surfaces and working actions, not a separate tutorial mode, unless the domain is high-stakes enough to need a sandbox. +- **Optional when possible.** Never block access to the product; experienced users can skip. +- **Time to value.** Front-load the 20% that delivers 80% of the value; leave advanced features to contextual discovery. +- **Context over ceremony.** Teach a feature when the user meets it. Empty states are onboarding. +- **Respect intelligence.** Be brief; do not explain standard patterns. ### Empty states -Every empty state should answer: +Every empty state answers what will appear here, why it matters, and the first action. Where it helps, add an illustration or icon rather than text alone, and a contextual help link. Match the kind: + +- **First use:** emphasize value; offer a template or example. +- **User cleared:** light touch; make recreating easy. +- **No results:** suggest another query or a way to clear filters. +- **No permission:** explain why and how to get access. +- **Failed load:** say what happened and offer a retry. -1. What will appear here? -2. Why does it matter? -3. What is the first action? +Do not fake real objects; label examples and templates as such. -Do not fake real objects unless they are clearly examples or templates. +### First run and first success -### Guided first action +- Welcome: what the product is, what the user will accomplish, an honest time estimate, and a skip. +- Setup: collect the minimum, explain why each field is asked, and use smart defaults. +- Introduce one to three core concepts by doing, not reading. +- Keep the first action small and reversible when possible. Show an honest pending state while the work runs, and move to the confirmed created item or next step only after the backend confirms success. Celebrate briefly. -- Keep the first action small and reversible when possible. -- Use templates, seed data, or defaults when they reduce blank-page anxiety. -- Show truthful pending state while work is happening. -- Move to the confirmed created item or next step after success. +### Contextual help, tours, and announcements -### Contextual help +- Prefer inline help, `details`/`summary`, popovers, and small disclosures at the point of use. +- Help patterns: keyboard-shortcut hints on the controls they trigger, searchable help, and "Learn more" links from tooltips and complex features. +- Progressive discovery: badge new or unused features and unlock complexity gradually instead of showing every option at once. +- Tours only for complex or changed interfaces: three to seven steps, interactive with real controls, workflow-framed ("create a project", not "this is the project button"), skippable, replayable from help, never blocking the whole UI. +- Interactive tutorials only when users need hands-on practice: sample data, a clear objective, validation that the user did it, and a graduation moment. +- Announcements say what is new and why it matters, let users try it immediately, and dismiss cleanly. -Use inline help, details/summary, popovers, or small local disclosures. Persist dismissals in backend user preferences only when they matter across sessions. Device-local hints are acceptable for non-critical tips. +### Progress and dismissal -### Progress +- Steps that represent account or data state complete only after backend confirmation. Never mark one done optimistically. Tour steps and device-local hints are local affordances. +- Durable completion and dismissals that matter across sessions or devices live in backend user state. Device-local hint visibility is acceptable for non-critical tips and is a local affordance only. +- Never show the same onboarding twice; returning users do not see initial onboarding again. -Progress indicators should reflect backend-known completion when it affects account state. Do not mark steps complete optimistically. +Use the main `cheers` skill for exact action, patch, and test mechanics. ## Avoid -- Forced long tours before users can work. +- Forced long tours before users can work, or a hidden skip. - Repeated tooltips that ignore dismissal. - Modal-first teaching. -- Separate tutorial mode disconnected from real data unless the domain is high-stakes. -- Patronizing obvious explanations. +- Information dumped upfront instead of disclosed progressively. +- Patronizing explanations of obvious controls. -## Cheers fit +## Verify -- Empty, first-run, and permission states should be first-class UI patterns. -- Local hint visibility can be a client affordance; durable completion belongs in backend state. -- Use `cheers` for exact action, patch, and test mechanics. +Check with evidence in one batched round (desktop and mobile together), fix what it shows in one batch, and confirm with at most one more round: -## Verify +- a new user reaches first value in the stated number of steps; an experienced user can skip at every step; +- every empty state kind present answers what, why, and the first action; +- no account or data step, check mark, or progress value appears before the backend confirms it, and pending never reads as done; +- errors are recoverable in place, with input preserved; +- the flow works with keyboard and screen reader, on touch (targets usable, nothing hover-only, no gesture as the only path), on a slow network, and with reduced motion; +- the final mechanical scan has no unexplained findings. -Can a new user reach first value quickly? Can an experienced user skip? Are errors recoverable? Does the flow work with keyboard, mobile, slow network, and reduced motion? +Format changed templates with `cargo cheers fmt --rustfmt `. When the flow holds, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/operate.md b/skills/cheers-design/reference/operate.md new file mode 100644 index 0000000..a4d3e15 --- /dev/null +++ b/skills/cheers-design/reference/operate.md @@ -0,0 +1,65 @@ +# Operate mode depth (and Read notes) + +Use this when design serves a task: app shells, authenticated UI, dashboards, settings, admin tools, forms, tables, workflows, and data surfaces. The essentials live in SKILL.md's visitor modes, [modes.md](modes.md), and [craft-floor.md](craft-floor.md); this file is extended depth. Read surfaces (docs, guides, long-form) take this file's typography and consistency rules; their prose measure and navigation matter more than component density. + +## The product slop test + +Familiarity is often a feature here. The test is whether a category-fluent user can trust the interface immediately or must pause at every subtly-off control, density, spacing, or term. + +Product UI fails when it is strange without purpose: over-decorated buttons, mismatched form controls, gratuitous motion, display fonts where labels should be, invented affordances for standard tasks, color used as decoration. The bar is earned familiarity. The tool should disappear into the task. + +## Typography + +- **One family is often right.** A well-tuned sans carries headings, buttons, labels, body, and data. System fonts and familiar sans families are legitimate. +- **Fixed rem scale, not fluid.** Clamp-sized headings don't serve product UI; a fluid h1 that shrinks in a sidebar looks worse, not better. +- **Tighter scale ratio.** 1.125–1.2 between steps is typical. Larger contrast is fine for page titles and onboarding. +- **Line length still applies to prose** (65–75ch). Data and compact UI can run denser; tables at 120ch+ are fine. +- Use tabular numerals for aligned numeric data. + +## Color + +Restrained is the floor: tinted neutrals plus one accent used with discipline. A single surface can earn Committed (a dashboard where one category color carries a report, a drenched welcome screen in onboarding), and [modes.md](modes.md) asks color to do real jobs in the shell. + +- Standardize a state vocabulary: hover, focus, active, disabled, selected, loading, error, warning, success, info. +- Accent color marks primary actions, current selection, focus, and state, not decoration. +- Use a second neutral layer for sidebars, toolbars, and panels, slightly cooler or warmer than the content surface. +- Charts and status systems need distinguishable shape, labels, and contrast, not color alone. + +## Layout + +- Predictable grids are an affordance; users move faster when structure stays stable. +- Familiar navigation, breadcrumbs, tabs, tables, filters, and form layouts are features, not failures of imagination. +- Use density deliberately. Empty space should clarify relationships, not pad the surface. +- Responsive behavior is structural: collapse sidebars, reflow columns, adapt tables, keep primary actions reachable. Not fluid typography. + +## Components + +Every interactive component has default, hover, focus-visible, active, disabled, pending, error, and success states where relevant. Don't ship half of them. + +- Loading states preserve layout (skeletons over spinners in the middle of content) and set expectations without implying success. +- Empty states teach the interface: what will appear, why it matters, the first useful action. Never just "nothing here". +- Consistent affordances across the surface: same button shape, same form-control vocabulary, same icon style. Icons have accessible names or surrounding text. +- Overlays escape their container. An absolutely positioned dropdown inside an `overflow: hidden` or `overflow: auto` ancestor gets clipped; reach for ``, the popover API, or `position: fixed`. + +## Motion + +- 150–250ms on most transitions. Users are in flow; don't make them wait for choreography. +- Motion conveys state: change, feedback, loading, reveal, navigation context. Nothing else. +- No orchestrated page-load sequences. Product loads into a task. +- Reduced-motion mode must still feel finished. + +## Product constraints + +- Decorative motion that doesn't convey state. +- Inconsistent component vocabulary across screens. If the "save" button looks different in two places, one is wrong. +- Display fonts in labels, buttons, or data. +- Reinventing standard affordances for flavor (custom scrollbars that hurt usability, weird form controls, non-standard modals). +- Heavy color or full-saturation accents on inactive states. +- Modal as first thought. Exhaust inline, page, and progressive alternatives first. + +## Product permissions + +- System fonts and familiar sans defaults. +- Standard navigation patterns: top bar plus side nav, breadcrumbs, tabs, command palettes. +- Density: tables with many rows, panels with many labels, dense information when users need it. +- Consistency over surprise. Delight is saved for earned moments, not pages. diff --git a/skills/cheers-design/reference/optimize.md b/skills/cheers-design/reference/optimize.md index b761e5a..32a4ff8 100644 --- a/skills/cheers-design/reference/optimize.md +++ b/skills/cheers-design/reference/optimize.md @@ -1,71 +1,92 @@ # Optimize -Improve perceived and measured UI performance by measuring the bottleneck, then choosing the smallest fix. Do not import client-heavy habits from browser-first frameworks unless this app actually uses them. +Improve perceived and measured UI performance by measuring the bottleneck for this interface, then choosing the smallest fix. A Cheers app renders HTML on the server and patches it with a small Datastar runtime, so the usual cost centers are server response time, asset weight, patch size and frequency, and paint; do not import bundle-splitting and memoization habits from client-heavy frameworks unless this app actually ships that code. -## Measure first +## Visitor mode -Identify what is slow or unstable: +- **Persuade + Experience:** the first viewport, its imagery, and its one authored motion must arrive fast and stable. Keep the committed world; bound expensive effects instead of deleting them. +- **Operate + Read:** speed is the feature. Action latency, list and table size, and update churn matter more than first paint; removing spectacle often helps more than adding infrastructure. -- initial HTML response -- CSS, font, and image loading -- action latency and perceived pending time -- live update throughput -- size or frequency of DOM updates -- layout, paint, blur, filter, shadow, or animation cost -- client JS execution -- browser memory for large DOM/list surfaces +Refinement preserves: optimize inside the established world and behavior. A fix that changes what the user sees, removes a state, or weakens trust is a design change; name it and ask. -Use project tooling, browser DevTools, server logs, Lighthouse/WebPageTest when relevant, and before/after timings. Do not optimize what is not slow. +## Two isolated assessments -## User-centered priorities +When a subagent tool is available and permitted, run these independently; otherwise run them yourself in this order. -### 1. Make waiting honest and useful +1. **Perceived-performance assessment.** Use the surface as the user does and answer each question with rendered evidence: + - **First view:** How long until the primary content and action are usable? Does anything shift, flash unstyled, or swap fonts visibly? + - **Actions:** Does feedback appear next to the control within about 100ms? Does the wait say what is happening, or does the UI freeze? + - **Updates:** Do streamed or patched regions flicker, jump, steal focus, or reset scroll? + - **Motion and paint:** Does scrolling or animation stutter, especially on blur, filters, shadows, or large fixed layers? + - **Scale:** How does the surface behave with realistic data volume, on a slow phone, on a throttled connection? +2. **Measurement.** The mechanical pass here is numbers, not the anti-pattern scan. Record before values for what the first assessment flagged: + - Core Web Vitals: LCP (under 2.5s), INP (under 200ms), CLS (under 0.1). + - Server: initial HTML response time and action round trip, from server logs or DevTools timing. + - Assets: CSS, font, image, and JS bytes and request count; cache headers on static assets. + - Live updates: patch payload size, frequency, and morph cost; open stream connections per page. + - Runtime: long tasks, frame rate, DOM size, memory on large lists. -- Show clear pending state near the action. -- Preserve layout during loading. -- Use progress, step labels, or partial results when the backend can truthfully provide them. -- Do not use skeletons or shimmer as a substitute for understanding the wait. +Use browser DevTools (Performance, Network, Lighthouse), WebPageTest, and server logs, on throttled CPU and network. Keep the measurements out of the first assessment, then synthesize: optimize what is both slow and felt. -### 2. Reduce visual and asset weight +## Set the budget -- Serve correctly sized images with dimensions. -- Prefer modern formats where the project supports them. -- Lazy-load below-fold media, not above-fold LCP media. -- Subset fonts and load only used weights. -- Remove icon sets, scripts, or styles that are not serving the surface. +Before editing, name the bottleneck, the metric that proves it, the target value, and the smallest fix that could reach it. Fix the biggest bottleneck first; skip micro-optimizations while a major one stands. -### 3. Simplify dynamic surfaces +## Apply -- Prefer one understandable region update over many scattered micro-updates when that is clearer. -- Avoid full-page updates for tiny status changes when a stable local region is obvious. -- Keep local client affordances small. -- For long lists, prefer backend pagination, filtering, or chunking before browser virtualization. +Read [craft-floor.md](craft-floor.md) before editing UI. Implement through `cheers` for patch, stream, signal, asset, and JS choices. -Use the main `cheers` skill for exact patch, stream, signal, and JS implementation choices. +### Make waiting honest -### 4. Optimize CSS and motion +- Pending feedback sits next to the control that caused it and appears immediately. +- Preserve layout during loading; reserve space for content that will arrive. +- Show progress, step labels, or partial results only when the backend can truthfully provide them. Never invent progress. +- No optimistic UI as a speed trick. Perceived speed comes from immediate, honest pending feedback and fast backend confirmation, never from showing success early. +- Skeletons and shimmer do not substitute for understanding the wait. -- Use transform and opacity for common movement. -- Avoid unbounded blur/filter/shadow effects. -- Do not casually animate layout-driving properties. -- Use `content-visibility` or pagination for very long independent content only when measured helpful. -- Keep DOM depth reasonable by removing wrapper noise and extracting meaningful components. +### Server and HTML + +- Slow first HTML is usually a slow query or blocking work in the handler; fix it there before touching the front end. +- Stream or defer slow, independent regions so the primary content renders first, each with an honest loading state. +- Paginate, filter, or chunk on the backend before reaching for browser virtualization. +- Compress responses and cache static assets with long-lived, fingerprinted URLs. +- Prefetch a likely next page only when the request is a safe, side-effect-free GET. + +### Assets + +- Images: correct dimensions or `aspect-ratio`, `srcset` and `sizes`, modern formats (AVIF, WebP), compression around 80 to 85% quality. Lazy-load below-fold media; never the LCP image, which can be preloaded. +- Fonts: subset, load only used weights, `font-display: swap` or `optional`, preload the critical face, and use metric-compatible fallbacks. System fonts are legitimate on Operate surfaces. +- CSS: remove unused rules, keep critical CSS small, use `contain` for independent regions. +- JS: remove icon sets, scripts, and third-party tags that do not serve the surface. Static JS helpers load only on pages that use them. -## Loading patterns +### Dynamic updates -- Initial loading fallbacks should be accessible and layout-stable. -- Action pending states should be adjacent to the control that caused them. -- Empty, partial, and error states should not cause large layout jumps. -- Performance-critical product UI often improves by removing spectacle, not adding it. +- Patch the smallest stable region that reads clearly; prefer one understandable region update over many scattered micro-updates, and avoid full-page patches for tiny status changes. +- Throttle or coalesce high-frequency stream updates to what a person can read. +- Keep signals small and local; they are affordances, not a client-side data store. +- Debounce search-as-you-type input before it reaches the backend. +- Never inject content above existing content, especially from patches and streams; it shifts layout (CLS). + +### Rendering and motion + +- Animate transform and opacity for common movement; blur, filters, masks, clip paths, and shadows stay available when bounded to small, isolated areas. +- Do not casually animate layout-driving properties (width, height, top, left, margins). +- `will-change` only for known expensive operations, removed when done. +- `content-visibility: auto` for long, independent content when measurement shows it helps. +- Keep DOM depth reasonable by removing wrapper noise and extracting meaningful components. +- In remaining static JS helpers, batch DOM reads before writes, use `requestAnimationFrame` for visual updates, throttle scroll and resize handlers, break up long tasks, and defer non-critical JS (INP). +- Never sacrifice accessibility, reduced-motion support, or working behavior for a number. ## Verify +Re-measure the same metrics under the same conditions, desktop and throttled mobile in one batched round, including a low-end Android device and real-user monitoring where available. Fix what remains in one batch and confirm with at most one more round. Check that every state and action still works and that it feels faster, not only scores better. + Report: -- what was measured +- what was measured, and how - what changed -- observed impact +- before and after values - trade-offs -- remaining bottleneck +- the remaining bottleneck -Then run relevant formatting and tests through the main `cheers` guidance. +Format changed templates with `cargo cheers fmt --rustfmt ` and run targeted checks through `cheers` guidance. When the user-facing numbers move, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/overdrive.md b/skills/cheers-design/reference/overdrive.md index e7242ee..8879ae6 100644 --- a/skills/cheers-design/reference/overdrive.md +++ b/skills/cheers-design/reference/overdrive.md @@ -1,6 +1,6 @@ # Overdrive -Push a Cheers interface beyond conventional quality with ambitious but context-appropriate polish. This command has a high risk of excess; propose before building. +Push a Cheers interface past conventional limits using the full power of the browser: a table that stays smooth over huge data, a dialog that morphs from its trigger, validation that streams back as the user types, a page transition that feels cinematic. Overdrive changes how an interface feels, not what the product does; real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Start your response with: @@ -9,47 +9,61 @@ Start your response with: 》》》 Entering design overdrive mode... ``` -## Gate +## Gate: propose before building -Before code, propose 2-3 directions and ask the user to pick. Include trade-offs for accessibility, browser support, performance, maintainability, and fit with the register. Do not implement until a direction is confirmed. +This command has the highest potential to misfire. -No optimistic UI. Extraordinary feedback still waits for backend confirmation before showing success or committed state. +1. Think through 2-3 directions that differ in technique, ambition, and aesthetic. Describe what each would look and feel like. +2. Get the user's pick before writing any code. Put each direction's description and its trade-offs (browser support, performance cost, accessibility, maintainability, JS weight) inside the option itself. A structured question can hide the message it rides in, so directions written alongside it may be invisible while the user chooses. +3. Build only the direction the user confirms. -## What extraordinary means +No optimistic UI. Extraordinary feedback still waits for backend confirmation before showing success or committed state; the wow lives in honest pending states and the confirmed transition, not in pretending. -- **Brand surface**: cinematic composition, scroll-linked reveals, generative background, art-directed image treatment, distinctive type choreography. -- **Product surface**: interaction that feels inevitable: instant-feeling but honest pending state, precise state transitions, keyboard-first density, large data that stays smooth. -- **Data-heavy UI**: clearer filtering, comparison, paging, density, and motion restraint before technical spectacle. -- **Performance-critical UI**: less visible drama, more absence of hesitation. +## Visitor mode + +Context decides what extraordinary means. A particle system on a portfolio is impressive; the same system on a settings page is embarrassing. Ask what would make a user of this specific interface say "that's nice". + +- **Persuade + Experience:** the wow is often sensory: a scroll-driven reveal, a shader or canvas ground, a cinematic transition between views, art-directed image treatment, type choreography. +- **Operate + Read:** the wow is in how it feels: a dialog that morphs from its button, a precise pending-to-confirmed transition, keyboard-first density, filtering that never flickers. On data-heavy screens, fluid transitions between data states and rendering that handles real volume. On performance-critical screens, the wow is invisible: the interface never hesitates. + +Overdrive works inside the established world. A new identity routes through [new-work.md](new-work.md). ## Toolkit, in design order -1. Semantic HTML and CSS: View Transitions, container queries, scroll-driven animations with fallbacks, custom properties, SVG. -2. Server-rendered confirmed states and coherent update regions. -3. Local affordances for reveal, selection, focus, and pending state. -4. Server-pushed or static JS only when the experience cannot stay declarative and the trade-off is worth it. -5. Canvas/WebGL/WASM only when the effect or scale demands it and fallback is defined. +Reach for the earliest layer that achieves the effect. Use `cheers` for exact implementation of anything server-rendered, patched, or streamed. -Use `cheers` for exact technical implementation. +1. **CSS and native features.** View Transitions (same-document broadly supported; cross-document not in Firefox), `@starting-style` for entry from `display: none`, scroll-driven animations (`animation-timeline: scroll()`, behind `@supports` with a static fallback), `@property` to animate typed custom properties, container queries, SVG and SVG filter chains. +2. **Hypermedia.** Server-rendered confirmed states, coherent update regions, server-side paging or windowing for large tables, and streams for live data or streaming validation. +3. **Local affordances.** Signals for reveal, selection, focus, and pending state. +4. **Static JS helpers,** only when the experience cannot stay declarative and the trade-off is worth it: Web Animations API for composable, cancellable choreography; spring physics; client-side virtual scrolling when the server cannot window the data. +5. **Canvas, WebGL, WASM,** only when the effect or scale demands it: Canvas 2D or OffscreenCanvas in a Worker to keep the main thread free; WebGL for shaders and large datasets; WebGPU (Chrome/Edge, Safari 26+, Firefox on Windows and macOS) always with a WebGL2 fallback; Web Workers or WASM for heavy computation. + +Sound and device APIs need explicit opt-in or permission and a user gesture. ## Implementation discipline -- Progressive enhancement is mandatory. -- Reduced-motion fallback must look intentional. -- Heavy resources lazy-initialize and stop when off-screen when possible. -- Backend truth remains authoritative. -- Do one browser inspection and at least one refinement pass. -- If the effect does not improve the experience when removed, remove it. +- **Progressive enhancement is mandatory.** Feature-detect every technique; the experience without the enhancement must still be good. +- **Performance:** target 60fps and simplify below 50. Lazy-initialize heavy resources (WebGL contexts, WASM modules) near the viewport and pause off-screen rendering. Check on a mid-range device profile, not only the development machine. +- **Reduced motion** gets an intentional static alternative, not a broken one. +- **Backend truth stays authoritative.** Normal navigation and history keep working; never replace them with a fragile custom state machine. +- **Polish the last 20%:** the easing curve, the stagger offset, the secondary motion that makes a transition feel physical. Ship the version that feels inevitable, not the first that works. +- Read [craft-floor.md](craft-floor.md) before editing; format changed templates with `cargo cheers fmt --rustfmt `. ## Never -- Add technical spectacle to mask weak layout, copy, or hierarchy. -- Ship janky effects. -- Use bleeding-edge APIs without fallback. -- Add sound without explicit opt-in. -- Layer multiple competing wow moments. -- Replace normal navigation/history with a fragile custom state machine. +- Use technical ambition to mask weak layout, copy, or hierarchy; fix those first with other commands. +- Ship effects that jank on mid-range devices or bleeding-edge APIs without a working fallback. +- Layer several competing wow moments. Focus creates impact; excess creates noise. +- Show success, removal, or reordering before the backend confirms it. ## Verify -Run the wow test, removal test, mid-range device test, reduced-motion test, keyboard test, and backend-failure test. Present limitations honestly. +Ambitious effects rarely land on the first try, so check the render instead of assuming it. Inspect desktop and mobile in one batched round, refine everything it shows in one batch, confirm with at most one more round, and report what still falls short rather than looping. Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) once over the changed page. Answer each with evidence: + +- **Wow:** would someone seeing it fresh react? +- **Removal:** take it away. If nobody would notice, remove it. +- **Device:** still smooth on a phone and a mid-range laptop? +- **Context:** does it fit this world and this audience? +- **Trust:** keyboard, reduced motion, slow network, and a failed backend action all behave honestly. + +Present limitations and fallbacks plainly. When the effect holds, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/polish.md b/skills/cheers-design/reference/polish.md index 23859f9..5a92bf3 100644 --- a/skills/cheers-design/reference/polish.md +++ b/skills/cheers-design/reference/polish.md @@ -1,54 +1,87 @@ # Polish -Refine an existing Cheers UI to shipping quality. Polish is not a rewrite unless the audit reveals structural problems. +Refine an existing Cheers UI to shipping quality. Polish is refinement, never concealed redesign: preserve the incumbent visual world, content, behavior, and everything outside scope. If the concept itself is wrong, say so and recommend a redesign through [new-work.md](new-work.md) or `bolder` instead of smuggling in a replacement. + +Additional context needed: the quality bar and shipping constraints. ## Preconditions -Polish assumes the core behavior exists. If the feature is still undefined or incomplete, run `shape` or `craft` first. +Polish is the last step, not the first. It assumes the core behavior exists; if the feature is undefined or incomplete, run `shape` or new-work first. + +## Visitor mode + +- **Persuade + Experience:** finish the committed world at full strength: the first viewport, the signature moment, the type voice, real imagery. Never sand the world down toward the category default in the name of cleanliness. +- **Operate + Read:** consistency is the polish. One component vocabulary, one state vocabulary, stable density, familiar affordances, per [operate.md](operate.md); on Read, measure, wayfinding, and the reading column. + +## Two isolated assessments + +Run these yourself in this order, or as independent subagents when the harness can spawn them. Keep scan output out of the first assessment, then synthesize both before editing. + +1. **Polish assessment.** Use the feature yourself in the running app at desktop and mobile in one batched round, with mouse, keyboard, and touch where applicable. Walk the path from the user's side before opening devtools. Determine: + - whether the path is functionally complete, and what is deliberately unfinished; + - the intended quality bar and the time available; + - the states, content lengths, roles, and input methods users will actually meet; + - where the flow, hierarchy, terminology, or disclosure drifts from neighboring features; + - where the interaction contract breaks Cheers guardrails: optimistic success, pending that reads as done, signals posing as durable state. +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) once over the target pages. Its findings are defect evidence, never proof of quality. + +**Prior critique.** Resolve the target to the same file path or URL critique would use, then: + +```bash +node /scripts/critique-storage.mjs slug "" +node /scripts/critique-storage.mjs latest +``` + +Exit 0 prints the latest snapshot: fold its P0/P1 findings into the backlog and name the snapshot you read. Exit 2 means none exists. The helper does not know whether the target changed since the critique, so confirm each finding against current code before acting on it. Run your own assessment either way. + +## Set the system + +Read DESIGN.md and representative tokens, shared components, patterns, and neighboring flows. Without a formal system, use the coherent conventions in code. Classify each drift before fixing it: + +- **missing token:** the system needs a reusable value; +- **one-off implementation:** an existing shared component or pattern should replace it; +- **conceptual mismatch:** the flow, information architecture, or hierarchy differs from comparable product areas; +- **local defect:** the implementation is simply incomplete or inconsistent. + +Fix the cause at the narrowest correct level; patching values does not fix a wrong flow. Ask when a binding system principle cannot be inferred. Before editing, state the authoritative tokens and components, the quality bar, the interaction contract on the path, and the triaged backlog. Then read [craft-floor.md](craft-floor.md). + +## Triage + +Fix in this order: -## Order of work +1. broken or blocked tasks, data loss, misleading or optimistic state, inaccessible paths; +2. missing loading, empty, pending, error, success, disabled, and permission states; +3. flow, hierarchy, responsive, and design-system drift; +4. visual and motion inconsistencies; +5. code and asset cleanup. -1. **Confirm intent**: primary action, register, target users, and release bar. -2. **Pull prior critique if available**: resolve the target to a stable file path or URL, compute its slug with `node /scripts/critique-storage.mjs slug ""`, then run `node /scripts/critique-storage.mjs latest `. Exit 0 means a snapshot exists; read it, fold P0/P1 findings into the polish backlog, and mention that a prior critique for `` was read. Exit 2 means no snapshot; continue without it. -3. **Discover the design system**: tokens, component vocabulary, spacing scale, typography, motion, icon set, and neighboring surfaces. -4. **Inspect the rendered UI** when practical. Source-only polish misses alignment, rhythm, and state problems. -5. **Fix trust and state coverage**: empty, loading, pending, error, success, disabled, permission, overflow, long text. -6. **Fix accessibility**: semantics, labels, focus, keyboard, status announcements, contrast, touch targets. -7. **Fix visual craft**: hierarchy, spacing, alignment, typography, color, density, responsive behavior. -8. **Fix copy**: labels, button verbs, status text, error recovery, repeated intros, filler claims. -9. **Triage cosmetic vs functional**: functional defects that block or confuse the experience ship first; cosmetic refinements can follow. Do not perfect one corner while leaving a P0/P1 trust, state, or accessibility issue unresolved. -10. **Validate through `cheers` guidance**: formatting, targeted tests, and implementation checks. +Do not perfect one corner while leaving the rest below the same bar. -## Design-system alignment +## Apply -For every drift, classify the root cause: +Build to the craft floor without restating it. Implement through `cheers` for templates, actions, patches, and signals. -- **Missing token**: a semantic value should exist but does not. -- **One-off implementation**: a shared pattern already exists but was bypassed. -- **Conceptual misalignment**: the flow, IA, or hierarchy does not match neighboring features. +- **Flow and hierarchy:** match neighboring mental models, terminology, disclosure, routing, and save behavior. Outcomes stay backend-confirmed even where a neighbor cheats. Make the primary task and current state obvious without flattening everything to equal weight. Connect arrival, transition, empty, and recovery paths instead of leaving isolated screens. +- **Layout and type:** align to the project's grid and spacing scale, optically as well as mathematically. Group related content tightly, separate distinct groups generously. Keep same-role type consistent; test measure, wrapping, localization expansion, zoom, and font loading at every supported viewport, not only the current screenshot. +- **Color, imagery, icons:** semantic tokens with stable meanings across themes; text, control, and focus contrast in every state; one icon family, stroke, size, and optical alignment; images with correct aspect ratios, responsive sources, useful alt text, and no layout shift. +- **Interaction and state:** every control has default, hover, focus-visible, active, disabled, pending, error, and success treatment where relevant. Pending says what is happening and blocks risky repeats; success appears only after the backend confirms it. Keep visible focus, logical tab order, labels, and 44px touch targets. Custom drag, slider, and scroll controls complete their gesture under touch, do not swallow page scroll, and clear their state on cancel. Motion stays coherent, interruptible, and performant; do not add animation to make polish visible. +- **Copy:** consistent terminology, capitalization, and punctuation. Concrete button verbs ("Save project", "Retry upload"). Errors say what happened and how to recover; loading text is truthful ("Saving...", not "Saved"). Remove repeated headings and intros, em dashes, and filler such as "seamless" or "powerful" unless the product voice uses them. Ask before changing factual copy or claims. +- **Code:** remove debug output, dead code, unused imports, obsolete styles, and polish-created duplication. Replace custom implementations with shared components where the system owns the pattern. Promote genuinely reusable values to tokens; never abstract one local exception. Reach for CSS and native browser behavior before signals, and signals before JS. -The fix differs by cause. Do not just patch values when the flow itself is wrong. +## Verify -## Visual polish checklist +One batched round at mobile, desktop, and an intermediate width whenever the layout reflows between them, fix everything it shows in one batch, then at most one confirming round. Answer each check with rendered or source evidence, not a bare yes: -- One primary action is visually and semantically clear. -- Related elements are close; unrelated groups have enough separation. -- Controls have default, hover, focus-visible, active, disabled, pending, error, and success treatments where relevant. -- Spacing follows a rhythm; avoid identical padding everywhere. -- Text has readable measure and does not overflow at mobile or 200% zoom. -- Product UI uses consistent component vocabulary and disciplined accents. -- Brand UI has a specific visual idea and real imagery/illustration when content demands it. -- No gradient text, decorative glass, nested card stacks, side-stripe card accents, generic hero metrics, or endless equal icon-card grids. -- Mobile behavior is structural, not just squeezed desktop. +- loading, empty, pending, error, success, disabled, long-content, missing-content, offline, and slow-connection states; +- zoom, contrast, focus, semantics, screen-reader names, and status announcements on patched regions; +- the primary touch gesture on custom controls, naming what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested; +- console errors, layout shift, interaction latency, and image loading in every supported browser; +- agreement with DESIGN.md, neighboring features, the surface brief, and the user's scope. -## Copy polish +Do not run another scan beyond the one in the assessment; fix real defects and document only narrow intentional exceptions. A clean scan does not replace visual judgment. -- Remove repeated headings and intros. -- Prefer concrete verbs on buttons: "Save project", "Invite member", "Retry upload". -- Error copy says what happened and how to recover. -- Loading copy is truthful: "Saving...", "Checking availability...". -- Avoid em dashes and vague filler such as "seamless", "powerful", "easy-to-use" unless the product voice truly uses them. +Format changed templates with `cargo cheers fmt --rustfmt ` and run the targeted checks `cheers` prescribes. Finish with a review of the source diff: remove accidental churn, orphaned code, redundant values, and temporary artifacts. Ship only when the feature is functionally complete and consistently finished across the path. -## Validation +## Hand off -After edits, use the main `cheers` skill for formatting and checks. At minimum, format changed Cheers templates and run targeted tests/checks appropriate to the behavior changed. +Report what changed, the states and viewports verified, the checks run, any snapshot read with which of its P0/P1 findings this pass resolved and which remain, and intentional exceptions. When the pass took findings from a snapshot, recommend `cheers-design critique` on the same target to record a fresh snapshot, so the next polish does not inherit a resolved backlog. diff --git a/skills/cheers-design/reference/product.md b/skills/cheers-design/reference/product.md deleted file mode 100644 index fc3cc13..0000000 --- a/skills/cheers-design/reference/product.md +++ /dev/null @@ -1,66 +0,0 @@ -# Product register - -Use this when design serves a task: app shells, authenticated UI, dashboards, settings, admin tools, forms, tables, workflows, and data surfaces. - -## Product slop test - -The test is not whether the UI is surprising. The test is whether a user fluent in strong tools would trust it immediately or pause at subtly odd controls, density, spacing, or terminology. - -Product UI fails when it is strange without purpose: over-decorated buttons, mismatched controls, gratuitous motion, display fonts in labels, invented affordances for standard tasks, or colors used as decoration. The bar is earned familiarity. The tool should disappear into the task. - -## Typography - -- System fonts and familiar sans families are legitimate. -- One family is often enough. Product UIs need clear roles more than display/body pairing. -- Use a tight fixed rem scale. Fluid display sizing usually belongs to brand surfaces, not dense tools. -- Use 1.125-1.2 ratios between type steps for compact UI. Larger contrast is fine for page titles and onboarding. -- Keep prose around 65-75ch. Dense data can run wider when scanning and comparison matter. -- Use tabular numbers for aligned numeric data. - -## Color - -Product defaults to **Restrained**: tinted neutrals plus one accent used with discipline. - -- Accent color means primary action, current selection, focus, or important semantic state, not decoration. -- Maintain a state vocabulary: hover, focus, active, disabled, selected, loading, error, warning, success, info. -- Use a second neutral layer for sidebars, toolbars, panels, and raised surfaces. -- Charts and status systems need distinguishable shape, labels, and contrast, not color alone. - -## Layout - -- Predictable grids are an affordance. Users move faster when structure stays stable. -- Familiar navigation, breadcrumbs, tabs, tables, filters, and form layouts are features, not failures of imagination. -- Use density deliberately. Empty space should clarify relationships, not pad the surface. -- Responsive behavior is structural: collapse sidebars, reflow columns, adapt tables, keep primary actions reachable. - -## Components - -Every interactive component needs visible default, hover, focus-visible, active, disabled, loading, error, and success states where relevant. - -- Empty states should explain what will appear, why it matters, and the first useful action. -- Loading states should preserve layout and set expectations. -- The same control should look and behave the same across the product. -- Icons must share a style and have accessible names or surrounding text. - -## Motion - -- 150-250ms for most transitions. -- Motion communicates state: feedback, loading, reveal, selection, navigation context. -- Avoid choreographed page-load sequences in task UI. -- Reduced-motion mode must still feel finished. - -## Product bans - -- Decorative motion that does not convey state. -- Inconsistent component vocabulary across screens. -- Display fonts in labels, buttons, or dense data. -- Reinventing standard controls for flavor. -- Heavy full-saturation accents on inactive or decorative elements. -- Modal-first flows where inline, page, or progressive disclosure would fit better. - -## Product permissions - -- Familiar patterns, native-feeling controls, and system fonts. -- Density for expert workflows. -- Consistency over surprise. -- Delight at earned moments, not everywhere. diff --git a/skills/cheers-design/reference/quieter.md b/skills/cheers-design/reference/quieter.md index c541f18..67e4341 100644 --- a/skills/cheers-design/reference/quieter.md +++ b/skills/cheers-design/reference/quieter.md @@ -1,56 +1,85 @@ # Quieter -Reduce visual noise without making the interface generic. Quiet design depends on precision. +Reduce visual intensity in a Cheers UI that is too loud, aggressive, or overstimulating without losing personality or turning generic. Quiet design is harder than bold design: subtlety needs precision, and quiet without intent collapses to the category default. -## Register +## Visitor mode -- **Product**: reduce decoration, motion, color, and competing affordances so the task is easier. -- **Brand**: lower intensity while preserving a specific point of view. +- **Persuade + Experience:** a more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the point of view stays intact. +- **Operate + Read:** less visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task. -## Assess +Quieting refines the established world. If the user wants a different, calmer identity rather than a calmer surface, that is a redesign and routes through [new-work.md](new-work.md). -Find intensity sources: +## Two isolated assessments -- too many saturated colors -- too many borders, shadows, backgrounds, cards, or icons -- all elements competing for attention -- dramatic motion where users are trying to work -- dense copy or repeated explanations -- inconsistent component treatments +Run these in order, and do not let scan findings anchor the design assessment. With subagents available, run them independently. -## Refine +1. **Design assessment:** find the intensity sources, with file, selector, or rendered evidence: + - saturation: too many bright or fully saturated colors; + - contrast extremes: high-contrast juxtaposition everywhere instead of where it matters; + - weight: bold, heavy elements competing, with no clear anchor; + - surfaces: too many borders, shadows, backgrounds, cards, or icons; + - motion: dramatic or decorative effects where users are trying to work; + - scale: everything large, no hierarchy; + - copy: dense text or repeated explanations; + - inconsistency: one component treated several ways. + + Then name what is working and the core message to preserve. Some contexts need energy; if purpose, audience, or what must survive is unclear from the code and briefs, ask rather than guess. +2. **Mechanical scan:** run the [mechanical scan](../SKILL.md#mechanical-scan-optional) over the target page. + +Synthesize both before editing. + +## State the system + +Before editing, name the few elements that stay bold (very few), what recedes, what can be removed outright, and how restraint will signal quality. Keep the world's palette, faces, and motif; quieter changes their intensity, not their identity. + +## Apply + +Read [craft-floor.md](craft-floor.md) first. ### Color -- Move product UI toward Restrained. -- Reserve accent for primary action, active state, focus, or semantic status. -- Desaturate brand colors rather than replacing them with gray. -- Use tinted neutrals, not pure gray, black, or white. -- Keep contrast strong enough for text and controls. +- Desaturate rather than replace: shift loud hues toward 70–85% of their saturation instead of swapping them for gray. +- Use fewer colors more deliberately; let tinted neutrals do more work and color act as accent (about 10%). +- On Operate and Read surfaces move toward Restrained, reserving accent for primary action, selection, focus, and semantic status. +- Keep high contrast where it matters: text, controls, and status. Never gray text on color; use a darker shade of that color or transparency instead. -### Type and hierarchy +### Weight and type -- Reduce excessive weights and sizes, but keep clear hierarchy. -- Let spacing and alignment carry more emphasis. +- Step weights down (900 to 600, 700 to 500) and narrow scale jumps, but keep clear hierarchy and a few anchors. +- Let spacing and alignment carry emphasis that color and boldness carried before. - Trim copy before shrinking it. ### Surfaces -- Remove unnecessary card wrappers. -- Flatten shadows unless elevation communicates interaction/state. -- Replace heavy borders with spacing, tonal contrast, or hairlines. +- Remove decorative gradients, patterns, textures, glows, and stacked shadows. +- Remove unnecessary card wrappers; flatten layering where elevation does not communicate interaction or state. +- Replace heavy borders with spacing, tonal contrast, or hairlines. Simplify extreme radii and custom shapes. +- Bring rogue elements back to the grid and even out arbitrary spacing jumps. ### Motion -- Remove decorative motion. -- Shorten distances and durations. -- Keep only feedback, reveal, loading, or transition motion. -- Respect reduced motion. +- Remove decorative animation; keep feedback, reveal, loading, and transition motion. +- Shorten distances (10–20px rather than 40px) and durations; ease out gently with ease-out-quart (see [animate.md](animate.md) tokens), never bounce or elastic. +- Reduced motion must still feel finished. + +## Never + +- Make everything the same size or weight; hierarchy still matters. +- Remove all color; quiet is not grayscale. +- Strip personality instead of refining it. +- Weaken affordances, focus, or contrast for calm. ## Cheers fit -Quieting must not hide state clarity. Keep pending, error, disabled, focus-visible, and semantic status treatments visible. Do not hide backend-confirmed failures to make the UI calmer. +Quieting must not hide state. Pending, error, disabled, focus-visible, and semantic status treatments stay visible, and backend-confirmed failures are never muted to make the UI calmer. Use `cheers` for implementation; format changed templates with `cargo cheers fmt --rustfmt `. ## Verify -The result should be easier to scan, still distinctive, still accessible, and still complete across states. If it became vague, run `clarify` or `layout` next. +Inspect desktop and mobile in one batched round, fix everything in one batch, confirm with at most one more round. Answer each with rendered or source evidence: + +- Users can still complete the task as easily, and controls read as controls. +- It still has character; the point of view survived the cuts. +- Long text is easier to read. +- Every state is still distinguishable, and the rerun scan has no unexplained findings. + +If the result turned vague, run `cheers-design clarify` or `cheers-design layout`. When it feels right, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/reference/routing.md b/skills/cheers-design/reference/routing.md new file mode 100644 index 0000000..d433fcc --- /dev/null +++ b/skills/cheers-design/reference/routing.md @@ -0,0 +1,30 @@ +# Command guidance + +## Workflow questions + +Give advice without executing commands; the menu below is only for bare invocations. Consult the relevant command references for prerequisites and scope. If the user also requests execution, follow that request. + +## No-argument routing: the context-aware menu + +Read this when the user invokes `cheers-design` with no argument. They are asking "what should I do?" Make the menu context-aware instead of static. **Never auto-run a command; the recommendation is a suggestion the user confirms.** + +Gather signals cheaply, in one pass: + +- whether `PRODUCT.md` and `DESIGN.md` exist, and whether the project has UI code (templates, components, stylesheets); +- the latest critique snapshots: `ls .cheers-design/critique/` and, for the most relevant slug, `node /scripts/critique-storage.mjs latest `; +- surface briefs in `.cheers-design/surfaces/`, especially any whose direction contract has no `FINISHED:` line; +- `git status --short`, to see which surfaces the dirty tree touches; +- whether a dev server is running, if the project's usual address is known. + +With no PRODUCT.md, lead with `cheers-design init` as the top recommendation (one line on why) and still show the rest. Otherwise lead with the **2–3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full Commands table from SKILL.md. Reason over the signals; there is no score to obey: + +- No DESIGN.md while UI code exists → `document` (capture the incumbent system). +- No critique snapshot for a real surface → `critique ` is a strong default. +- A latest critique with a low score or P0/P1 findings → `polish` on that surface (it reads the snapshot as its backlog). Snapshots are never closed, so when the target's files changed after the snapshot's timestamp (`git log -1 --format=%cI -- ` or the dirty tree), say the findings may be stale and suggest re-running `critique` instead. +- Changed files pointing at one surface → scope `audit` or `polish` to those files, naming them. +- A surface brief with an unfinished build → resume new-work's finish for that surface. +- Otherwise group by intent (build new / improve what's there), tailored to the current surface. + +When the [mechanical scan](../SKILL.md#mechanical-scan-optional) is available, run it once: over the main page when a dev server is running, otherwise over the project's stylesheets. Fold the hits into your picks: many quality or contrast hits → `audit` or `polish`; a specific family → the matching command (gradient text or eyebrows → `quieter` or `typeset`, flat or gray palette → `colorize`). If it errors, is slow, or is unavailable, skip it and recommend the user run `audit` themselves; never block the suggestion on it. + +Keep it to 2–3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede. diff --git a/skills/cheers-design/reference/shape.md b/skills/cheers-design/reference/shape.md index 07ae9b5..57c4a28 100644 --- a/skills/cheers-design/reference/shape.md +++ b/skills/cheers-design/reference/shape.md @@ -1,60 +1,74 @@ # Shape -Shape the UX/UI for a Cheers feature before code. Output a task-specific design brief that makes purpose, visual direction, states, and interaction contract explicit. +Discover what should be made and how it should work in a Cheers app, then return a confirmed design brief without code. The brief makes purpose, direction, states, and the interaction contract explicit. -## Discovery +## Phase 1: discovery interview -Ask only what is missing from the request, existing product docs, design docs, or code. With a sparse prompt, ask 2-3 questions and wait instead of inventing the whole brief. +Do not write code or choose visual direction yet. -Cover: +### Cadence -- **Purpose**: what problem this surface solves and the primary user action. -- **User context**: who uses it, where, under what pressure, and how often. -- **Success**: what the user should understand, complete, or trust afterward. -- **Content/data**: what is shown or collected, including min, typical, max, empty, and error cases. -- **Scope**: sketch, mid-fi, high-fi, or production-ready; one component, screen, or flow; static or interactive. -- **Register**: product or brand. Infer when obvious and ask for confirmation when consequential. -- **Visual direction**: color strategy, scene sentence, typography tone, density, imagery/media needs, references, anti-references. -- **Constraints**: existing design system, accessibility, localization, browser support, performance budget, and implementation boundaries. +- Use the structured question tool when available; otherwise ask and stop. +- Ask two or three related questions per round, then wait. One round is the default; add a second only when the answers expose a material gap. +- Do not dump a questionnaire, repeat settled facts from PRODUCT.md, DESIGN.md, or code, or turn obvious facts into menus. Assert the likely reading and invite correction. +- A sparse prompt requires at least one answer round. A precise prompt may need only a compact confirmation. -## Interaction contract +### Round 1: purpose, people, and outcome -Every brief must name how the interface changes over time, but keep it at design level: +Choose the two or three questions that most change the result: -1. **Backend-confirmed state**: durable data, derived view models, and success/error outcomes. -2. **User input**: what the user submits or edits, and how it survives validation errors. -3. **Local affordances**: open/closed, focus, selection, pending, reveal, and other client-only UI feelings. -4. **Refresh boundaries**: which conceptual regions update after actions or streams. -5. **Long-lived updates**: whether live progress or collaboration changes need a stream. -6. **JS-worthy behavior**: whether any behavior truly needs a static client helper rather than CSS/native/Cheers interaction. +- What is this surface or feature for, and what problem must it solve? +- Who specifically reaches it, in what situation and state of mind, and how often? +- What is the primary thing they must understand or do? What would success look like? +- What is uniquely true here that a neighboring product or generic template could not claim? + +### Round 2: material, behavior, and boundaries + +Run only for material unresolved decisions: + +- What real content, evidence, data, and assets must the experience carry? What are realistic minimum, typical, and maximum ranges? +- Which states and transitions matter: first-run, empty, loading, pending, error, success, permissions, overflow, or expert use? +- What is the intended fidelity, breadth, and interactivity: exploration, production-ready screen, full flow, or broader surface? +- What must remain untouched? What would make the result feel wrong even if it looked polished? +- Which accessibility, localization, browser, performance, or delivery constraints are binding? + +Never ask for CSS values or canned aesthetic lanes. New-work owns visual-world and concept choices. + +## Phase 2: resolve the design direction + +For new surfaces, brand expansion, or replacement, follow [new-work.md](new-work.md) through visual authority, any direction round, and the concept choice. Reuse discovery, then return here before its direction contract, persistence, or implementation. Inside an established world, use its structure round only when composition or interaction remains materially open. + +## Phase 3: name the interaction contract + +Every brief names how the interface changes over time, at design level: + +1. **Backend-confirmed state:** durable data, derived view models, and success or error outcomes. +2. **User input:** what the user submits or edits, and how it survives validation errors. +3. **Local affordances:** open/closed, focus, selection, pending, reveal, and other client-only UI feelings. +4. **Refresh boundaries:** which conceptual regions update after actions or streams. +5. **Long-lived updates:** whether live progress or collaboration needs a stream. +6. **JS-worthy behavior:** whether anything truly needs a static client helper rather than CSS, native browser behavior, or Cheers interaction. Reject briefs that require optimistic success, broad backend state mirrored into client affordances, or custom browser history for normal navigation. -## Brief structure +## Phase 4: write the brief + +Write the smallest useful brief: -Present the brief in this shape and ask for explicit confirmation: +1. **Job and audience:** who arrives, their context, need, and visitor mode. +2. **Outcome and proof:** primary task or action, success, real evidence, and product-specific truth. +3. **Selected direction:** visual authority, structural or interaction thesis, sequence, focal moment, and implementation consequence. +4. **Scope and boundaries:** fidelity, breadth, interactivity, named target, what remains untouched, and explicit anti-goals. +5. **States, ranges, and content:** realistic content and data ranges, required headings, labels, microcopy, error copy, and alt text, and the material states: default, empty, loading, pending, error, success, disabled, permissions, overflow, long text, mobile. +6. **Interaction and layout:** the interaction contract above, plus hierarchy, topology, responsiveness, affordances, feedback, and transitions. Intent, not CSS. +7. **Constraints and open decisions:** accessibility, localization, reusable components, relevant cheers-design references for the build, and choices a builder must not invent. -1. **Feature summary**: 2-3 sentences. -2. **Primary user action**: the one thing to make obvious. -3. **Register and visual direction**: product/brand, scene sentence, color strategy, typography/density, imagery, references or anti-references. -4. **Scope**: fidelity, breadth, interactivity, time intent. -5. **Layout strategy**: hierarchy, rhythm, grouping, responsive approach. -6. **Component and pattern plan**: likely UI patterns and reusable pieces, in design terms. -7. **Interaction contract**: backend-confirmed outcomes, inputs, local affordances, refresh boundaries, streams, JS need. -8. **Key states**: default, empty, loading, pending, error, success, disabled, permissions, overflow, long text, mobile. -9. **Content requirements**: headings, labels, microcopy, error copy, alt text, dynamic ranges. -10. **Build references**: which cheers-design reference files should guide implementation. -11. **Open questions**: unresolved choices that affect code or design. +Use three to five bullets when the task is settled; use the full structure only for ambiguous, multi-screen, or standalone planning. Do not restate the conversation. -Stop after asking for confirmation unless the user already supplied a confirmed brief or explicitly asks you to continue without confirmation. +Before presenting, check that the primary action is clear, the direction is specific enough to avoid category reflex, state coverage is complete enough for the requested fidelity, loading and errors are honest and accessible, responsive behavior is structural, and the contract can be built without optimistic UI. -## Quality checks +## Confirm and stop -Before presenting it, verify: +Present the brief for explicit confirmation or one correction round, then stop: shape never writes code or a direction contract. -- The primary action is clear. -- The visual direction is specific enough to avoid category reflex. -- State coverage is complete enough for the requested fidelity. -- Loading and errors are honest and accessible. -- Responsive behavior is structural. -- The interaction contract can be implemented without optimistic UI. +When no human or structured answer mechanism exists, mark assumptions plainly, return the brief, and stop. diff --git a/skills/cheers-design/reference/typeset.md b/skills/cheers-design/reference/typeset.md index bf45430..f4c2e6c 100644 --- a/skills/cheers-design/reference/typeset.md +++ b/skills/cheers-design/reference/typeset.md @@ -1,56 +1,71 @@ # Typeset -Improve typography hierarchy, readability, and font strategy in a Cheers UI. +Typography carries information, hierarchy, and voice. Improve it inside the established visual world; do not replace the identity unless the user asked to. -## Register +## Visitor mode -- **Product**: system fonts or one familiar sans are often correct. Use a tight fixed rem scale, clear label/body/title roles, and stable density. -- **Brand**: typography can carry the voice. Use stronger scale contrast, distinctive headings, and fluid display sizes when the surface earns it. +- **Persuade + Experience:** display type may carry the voice. Use decisive contrast and responsive (`clamp()`) display scale when the composition benefits. +- **Operate + Read:** stability, scanability, and measure come first. A single well-tuned family and a fixed `rem` role scale (about 1.125–1.2 between steps) are often right. See [operate.md](operate.md#typography). -## Assess +If typography replacement would create a new identity, route through [new-work.md](new-work.md) and update DESIGN.md. Otherwise preserve confirmed families and improve their use. -Check: +## Two isolated assessments -- Are headings, body, labels, captions, code/data, and buttons visually distinct? -- Is the scale too flat? -- Is body text at least `1rem` and readable at 200% zoom? -- Are line lengths reasonable, especially prose at 65-75ch? -- Are too many font families or weights loaded? -- Do data columns need tabular numbers? -- Does type overflow in patched states, validation errors, empty states, or long localized labels? +When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let scan findings anchor the design assessment. -## Improve +1. **Typographic assessment.** Inspect representative pages, states, and stylesheets. Answer every question with a file, selector, or computed value: + - **Authority and fit:** which faces, weights, and roles are established? Do they fit the product and its world, or are they unexamined defaults? Is every family necessary? + - **Hierarchy:** can heading, body, label, metadata, and data roles be told apart at a glance? Are adjacent sizes or weights too close to carry different jobs? + - **Scale and consistency:** is there a deliberate role scale or a collection of arbitrary values? Do repeated roles stay identical across screens and across pending, error, empty, and success states? + - **Reading:** does body copy hold a comfortable measure? Are line height, paragraph rhythm, contrast, and tracking tuned to the actual face, width, language, and surface? + - **Stress:** what happens with long headings, localization expansion, 200% zoom, narrow containers, backend-patched content, validation errors, missing weights, and font fallback? + - **Delivery:** are only used files and weights loaded? Do fallback metrics, `font-display`, and variable-font settings avoid invisible text and disruptive reflow? +2. **Mechanical scan.** Run the [mechanical scan](../SKILL.md#mechanical-scan-optional) with the type scope, for example `impeccable detect --json --scope type ` against the dev server. It cannot read `html!` templates, so also check inline style values and font sizes set in templates by hand. -### Product type +Synthesize both before editing, noting what each caught alone. A clean scan is a floor, not proof of good typography. -- Use semantic roles: label, body, title, heading, data, caption. -- Keep the scale tight and predictable. -- Do not use display fonts in labels, buttons, or dense data. -- Use tabular numerals where alignment matters. -- Prefer system or familiar sans stacks unless the design system says otherwise. +## Set the system -### Brand type +Before editing, state: -- Start from voice, not trend. Name what the type should feel like as a physical object. -- Use fluid display sizes and stronger contrast when the surface earns it. -- Choose distinctive type only when it supports the brand, not because it looks designed. -- Avoid reusing the same popular display families across unrelated projects. +- the roles the interface needs (for example label, body, title, heading, data, caption, code); +- the intended contrast between those roles; +- the reading measure and density; +- which existing faces and weights are authoritative; +- performance, localization, and accessibility constraints. -### Readability details +Use the fewest roles and families that make the hierarchy unmistakable. Combine size, weight, space, and tone instead of asking size alone to do the work. Name role tokens by purpose, not value: `--text-label`, not `--text-14`. -- Body line-height: about 1.45-1.7. -- Heading line-height: about 1.0-1.2. -- Increase line-height slightly for light text on dark backgrounds. -- Use `font-variant-numeric: tabular-nums;` for aligned numbers. -- Use `rem`, not fixed pixel font sizes. -- Load only weights you actually use. +## Apply -## Cheers fit +Read [craft-floor.md](craft-floor.md) before the first edit; its type checks (measure, display ceiling, tracking floor, scale steps) apply here and are not repeated. -- Keep type roles in CSS/design docs, not arbitrary inline styles in templates. -- Ensure error, success, empty, and pending states use the same typographic roles as the rest of the component. -- Use `cheers` for exact rendering syntax. +- Keep body copy readable and zoomable: `1rem` is the ordinary body floor unless a dense role, the design system, or a user setting justifies otherwise. Size in `rem`, never fixed pixels, so browser zoom and user font settings keep working. +- Hold body prose at the craft floor's measure with `max-width` in `ch`; narrow secondary columns may run down to about 45ch. Tune line height to the face, not a universal ratio, and inversely with measure: wider lines need more leading. Headings sit tighter, about 1.0–1.2. +- Compensate light text on dark surfaces on all three axes: slightly more line height, a touch more tracking, and one step more weight when the face needs it. +- Use one paragraph rhythm: spacing or first-line indent, not both. +- Use `font-variant-numeric: tabular-nums` for aligned numbers, and code or label features where the content benefits. +- Do not use display faces in labels, buttons, or dense data. +- Load only used weights and files. Self-host with metric-compatible fallbacks; never block text on a font. +- Let Persuade display type respond to available space; keep Operate and Read surfaces spatially predictable. + +Do not make type decorative at the expense of comprehension, and do not add a second family without a role only it can perform. + +### Cheers fit + +- Keep type roles in the project's stylesheets and tokens, not inline styles in `html!` templates. +- Pending, error, empty, and success states rendered by the backend use the same roles as the component they belong to; a patched error message is not a new typographic voice. +- Use `cheers` for rendering mechanics. Format changed templates with `cargo cheers fmt --rustfmt `. ## Verify -Check hierarchy, 200% zoom, mobile wrapping, long translations, contrast, and font loading. Finish with `polish` if spacing or state treatments still need work. +Inspect in one batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, then rerun the scan once. Answer each item with rendered or source evidence; a bare "yes" is not verification. + +- Primary, secondary, body, and metadata roles are recognizable without reading the copy. +- Long text stays comfortable across relevant widths, languages, and patched states. +- The typography belongs to the product and its established world. +- Loading causes no invisible text or disruptive reflow. +- Zoom, user font settings, focus, contrast, and narrow viewports remain usable. +- The final scan has no unexplained findings. + +When the hierarchy holds, hand off to `cheers-design polish`. diff --git a/skills/cheers-design/scripts/critique-storage.mjs b/skills/cheers-design/scripts/critique-storage.mjs index 92c9638..74dde80 100755 --- a/skills/cheers-design/scripts/critique-storage.mjs +++ b/skills/cheers-design/scripts/critique-storage.mjs @@ -39,7 +39,7 @@ export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) { } catch { return null; } - return kebab(`${url.hostname}${url.pathname}`); + return kebab(`${url.host}${url.pathname}`); } const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed); @@ -65,10 +65,7 @@ function kebab(value) { } export function nowFilenameStamp(date = new Date()) { - return date - .toISOString() - .replace(/[:.]/g, "-") - .replace(/-\d+Z$/, "Z"); + return date.toISOString().replace(/[:.]/g, "-"); } export function writeSnapshot({ @@ -174,8 +171,11 @@ function main(argv) { if (process.env.CHEERS_DESIGN_CRITIQUE_META) { try { meta = JSON.parse(process.env.CHEERS_DESIGN_CRITIQUE_META); - } catch { + } catch (error) { // Metadata is helpful but never blocks writing the human report. + process.stderr.write( + `ignoring invalid CHEERS_DESIGN_CRITIQUE_META: ${error.message}\n`, + ); } } const body = fs.readFileSync(bodyFile, "utf-8");