command-code 0.26.16 → 0.26.17

package/skills/design/references/button.md

@@ -0,0 +1,192 @@
+# Button Library
+
+Buttons are decisions made visible. They tell the user what can happen, what should happen, and what must be handled with care.
+
+I treat a button as an interaction contract, not a colored rectangle.
+
+---
+
+## Buttons Inherit The Work Pattern
+
+I do not reuse one button family everywhere.
+
+Monitor screens need compact controls for filters, acknowledgement, drill-down, and refresh.
+
+Operate screens need tool buttons, command buttons, icon buttons, and shortcut-ready actions.
+
+Compare screens need table actions, segmented controls, bulk selection, and quiet row commands.
+
+Configure screens need save, reset, preview, test, and dependency-aware disabled states.
+
+Learn screens need continue, back, skip, complete, and progress-aware actions.
+
+Decide screens need one unmistakable primary action and careful secondary escape.
+
+Explore screens need search triggers, filters, chips, clear all, and reversible navigation.
+
+The button shape follows that job. A centered pill CTA is not a universal answer.
+
+---
+
+## System Bar
+
+When an active mode consults this reference, I create or repair the button system. It is not a single CTA restyle.
+
+At minimum, I cover primary, secondary, tertiary, danger, icon-only when present, grouped controls when present, loading, disabled, hover, active, focus-visible, success or error resolution when relevant, mobile reach, and accessible names.
+
+If only one button exists, I still define how its unavailable, loading, focused, pressed, and completed states behave.
+
+---
+
+## The Hierarchy
+
+A screen gets one primary action. If there are two primary buttons, neither is primary.
+
+**Primary** is the main action. It gets the strongest visual treatment and the clearest placement.
+
+**Secondary** is a valid alternative. It supports the primary without competing.
+
+**Tertiary** is low-emphasis. It is for escape, navigation, supporting links, and quiet actions.
+
+**Danger** is destructive. It is never styled as the default path unless the whole surface is explicitly about confirming destruction.
+
+---
+
+## Shape And Size
+
+Button size follows context.
+
+Small buttons belong inside dense product UI, toolbars, tables, and inline actions. Medium buttons carry most product actions. Large buttons belong to mobile primary actions and brand CTAs.
+
+Icon-only buttons must keep a real hit target even when the visible icon is small.
+
+Radius follows the project. Product UI usually wants modest corners. Brand pages can be rounder. Technical and blocky systems can go square. Pills are for filters, tags, segmented controls, and specific brand languages. I do not mix radius styles casually.
+
+---
+
+## States
+
+Every button needs the states it can enter.
+
+Resting tells the user the action exists. Hover invites pointer users. Focus-visible guides keyboard users. Pressed confirms contact. Disabled explains that action is unavailable. Loading keeps the system accountable. Error and success resolve the action.
+
+A button that only has a resting style is unfinished.
+
+---
+
+## Motion
+ 
+Apply a scale-down effect on button press to signal responsiveness.
+ 
+**Implementation:**
+- On `:active` pseudo-class, scale to 0.97–0.98
+- Transition duration: ~150ms
+- Easing: ease-out
+
+A loading button does not freeze. Choose one:
+ 
+- **Spinner icon:** Smooth 360° rotation with a faster-spinning spinner makes the app seem to load faster
+- **Dot pulse:** Three dots fade in sequence (0 → 1 → 0), 400ms per dot, looping
+- **Width breathing:** Button width grows and shrinks 2-3px (200ms cycle) to signal activity
+- **Shimmer:** Subtle left-to-right shimmer across the label (1000ms, one pass per cycle)
+
+Pick one approach per design system. Do not combine.
+
+---
+
+## Text
+
+Button text names the action.
+
+I use one clear verb with an object when needed: save changes, create account, delete project, send invite, continue to payment.
+
+I avoid OK, Submit, Click here, vague Learn more, and yes/no labels when the action can be named. No exclamation points. Urgency comes from context, not punctuation.
+
+For destructive actions, I name the object and the consequence clearly.
+
+---
+
+## Placement
+
+Placement follows the decision structure.
+
+In dialogs and forms, the primary action sits where the flow resolves. Secondary actions stay nearby but quieter. Destructive actions move away from the safe path and lose visual dominance.
+
+On mobile, primary actions often need full width and reachable placement. Stacked buttons should keep the primary easy to find without making the secondary feel hidden.
+
+Toolbars place the strongest action where scanning naturally ends. Repeated toolbar actions keep the same order across screens.
+
+---
+
+## Icons
+
+Icons reinforce button text. They do not replace it unless the action is globally familiar and has an accessible name.
+
+Icon-only buttons need a clear accessible label and, on pointer devices, a tooltip when the icon can be misunderstood. The hit area remains large enough for touch.
+
+Icons must come from the same visual family. A button row with mismatched icon styles feels assembled.
+
+---
+
+## Groups
+
+Button groups are for choosing within one dimension: day, week, month; list, grid; light, dark, system.
+
+Grouped buttons share edges and state vocabulary. The selected item is obvious. The group does not pretend to be navigation unless it changes the current view.
+
+On mobile, a group can stack or become a segmented control, but the active state must remain unmistakable.
+
+---
+
+## Loading
+
+A loading button keeps the action anchored. It changes label or indicator so the user knows the system heard them.
+
+I disable repeat submission while the action is in flight. I preserve the button's footprint so the layout does not jump. Success resolves briefly. Failure returns control and explains recovery somewhere visible.
+
+Long operations can show progress. Routine saves do not need theater.
+
+---
+
+## Danger
+
+Danger buttons are serious.
+
+Recoverable destructive actions should prefer undo. Irreversible actions need confirmation with clear consequence text. The safe action gets dignity. The destructive action is specific and visually controlled.
+
+I never use danger styling for attention. Red is not a marketing accent.
+
+---
+
+## What I Refuse
+
+- Multiple primary actions on one decision surface
+- Calling one hero CTA restyle a button system
+- Leaving focus, disabled, loading, or danger states undefined
+- Vague labels like OK, Submit, Yes, or Click here
+- Icon-only buttons without accessible names
+- Tiny hit targets
+- Disabled buttons that look clickable
+- Loading states that collapse the layout
+- Danger as the default path for irreversible actions
+- Mixed radius styles without a system reason
+- Button shadows as default decoration
+
+---
+
+## How I Know Buttons Work
+
+- The button system covers real states, not only resting style
+- The main action is unmistakable
+- Button labels say what happens
+- Every reachable state has a visual answer
+- Keyboard focus is visible
+- Touch targets are physically usable
+- Danger actions are recoverable or clearly confirmed
+- Button groups show one clear selection model
+- The same hierarchy means the same thing across the product
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.

package/skills/design/references/checkup.md

@@ -0,0 +1,160 @@
+# Checkup: `/design checkup`
+
+I use checkup for fast design triage. It tells me whether an interface is basically healthy or whether something is unsafe to ship.
+
+This is not a deep critique. It is a vital-sign read.
+
+---
+
+## Composition Vital Sign
+
+I check whether the page shape matches the work.
+
+Monitor: can the user see priority, change, and freshness fast?
+
+Operate: are tools, targets, feedback, and undo close enough to use?
+
+Compare: do rows, columns, criteria, and filters support scanning?
+
+Configure: are choices grouped by dependency and consequence?
+
+Learn: does the flow create orientation and progress?
+
+Decide: is the next action obvious and supported by proof?
+
+Explore: are search, filters, results, and return paths easy?
+
+If the composition fails this vital sign, visual polish will not fix the surface.
+
+---
+
+## Prompt Fidelity Vital Sign
+
+I check whether the visible design matches the prompt invariants.
+
+The name must be exact when supplied. The category must be visible. The core artifact must belong to the domain. The proof must answer the user's pressure. The copy and layout must not reuse language or structure from an unrelated design.
+
+If the visible design could be reassigned to another random product by changing only the logo and headline, the checkup fails before style is considered.
+
+---
+
+## Evidence Bar
+
+`/design checkup` is a fast read, but it still needs evidence.
+
+At minimum, I inspect the rendered surface or actual implementation, touch the core task enough to judge it, and base every vital status on something visible, interactive, or present in files.
+
+If I cannot verify a vital, I mark it unknown or unverified. I do not invent health.
+
+---
+
+## What I Check
+
+I look at six vital signs.
+
+**Intentionality**: Does it look chosen, or does it look assembled from defaults?
+
+**Readability**: Can people read it comfortably, in its real contexts and themes?
+
+**Usability**: Can the primary task be completed with the available controls?
+
+**Responsiveness**: Does the surface adapt across width, input mode, zoom, and safe areas?
+
+**Speed**: Does it load and respond without visible hesitation, shift, or jank?
+
+**Accessibility**: Can keyboard, screen reader, color-blind, low-vision, and reduced-motion users operate it?
+
+When accessibility is weak, the whole checkup is weak. It affects real people, not just a score.
+
+---
+
+## Scoring
+
+Checkup uses a `/60` score across the six vital signs. **MAX_SCORE = 60.** Use `/60` as the denominator in the report template — never `/40` or `/10`.
+
+Each vital is scored by status:
+
+| Status | Points |
+|---|---|
+| Healthy | 10 |
+| Watch | 5 |
+| Critical | 0 |
+
+Six vitals × 10 pts max = 60 total. No normalization needed.
+
+The heuristics table in the report uses 6 rows (one per vital sign), each scored `/10`.
+
+## My Read
+
+I classify each vital as healthy, watch, or critical.
+
+Healthy means the surface is fit for continued work. Watch means the issue is real but contained. Critical means it blocks trust, task completion, access, or shipping confidence.
+
+I stop pretending everything is equally important. A broken keyboard path outranks a slightly dull palette. Illegible text outranks a missing hover flourish.
+
+---
+
+## Fast Probes
+
+I use short probes, not a ceremonial audit.
+
+I glance for purpose, primary action, and dominant color. I blur the page mentally and check whether hierarchy survives. I test the thumb path on narrow viewports. I tab through the core route. I look for obvious layout shift, slow media, contrast failure, and generated-design tells.
+
+These probes are small on purpose. Checkup is meant to catch danger quickly.
+
+---
+
+## Prescriptions
+
+For every critical issue, I write the prescription in my working answer:
+
+- What is broken
+- Why it matters
+- What command or design discipline should fix it
+
+I do not bury the next move in a report. The user should know the practical fix immediately.
+
+---
+
+## Report Boundary
+
+Checkup always produces two report artifacts:
+
+- `.commandcode/design/checkup-report.md`
+- `.commandcode/design/checkup-report.html`
+
+**Important Rule for Generating HTML Report:**
+
+- **Use the following template structure** [report-html.md](report-html.md) to generate `checkup-report.html`:
+- Do not change the visual design. Only fill in the content.
+
+These are the only report artifacts checkup creates.
+
+---
+
+## What I Refuse
+
+- Treating checkup as a full design review
+- Marking a vital healthy without evidence
+- Inventing checks I did not run
+- Creating extra report artifacts beyond `checkup-report.md` and `checkup-report.html`
+- Calling a surface healthy when keyboard users cannot finish the task
+- Ignoring mobile because desktop looks good
+- Letting performance scores hide visible jank
+- Letting a pretty surface pass with missing states
+
+---
+
+## How I Know Checkup Is Done
+
+- Each vital is backed by observed evidence or marked unverified
+- Each vital has a clear status
+- Critical issues have direct prescriptions
+- The core task has been touched, not just inspected visually
+- The user knows whether to proceed, fix, or pause
+- `checkup-report.md` and `checkup-report.html` both exist
+
+STRICT RULE — NEVER BREAK THIS
+Always create .commandcode/design/checkup-report.md and
+.commandcode/design/checkup-report.html. Do not create any other report,
+summary, analysis file, or extra documentation.

package/skills/design/references/color.md

@@ -0,0 +1,166 @@
+# Color: `/design recolor`
+
+I treat color as atmosphere, structure, and promise. A palette is not a bag of nice swatches. It is the emotional weather of the interface, the hierarchy system, and the accessibility contract.
+
+I pick color after I know what the surface is trying to make someone feel. Calm is a different palette from urgency. Trust is different from momentum. A brand page can flood the room. A product screen earns restraint.
+
+---
+
+## Pre-execution checklist
+
+Before proceeding, check for existing reports in the `.commandcode/design/` directory. Look for these files:
+
+- `checkup-report.md`
+- `review-report.md`
+- `smell-report.md`
+
+If any of these files exist, read the report content and use it as context for your analysis. Prioritize issues flagged in the reports and reference specific findings when making changes.
+
+If no reports are found, proceed with the task normally.
+
+---
+
+
+---
+
+## Color Follows Composition
+
+The work pattern decides where color is allowed to carry weight.
+
+Monitor surfaces reserve strong color for urgency, status, freshness, and thresholds.
+
+Operate surfaces use color to separate tools, active objects, selection, and feedback.
+
+Compare surfaces keep color stable across rows, columns, legends, and categories.
+
+Configure surfaces use color for dependency, validation, preview, and commit risk.
+
+Learn surfaces use color for pacing, section memory, progress, and emphasis.
+
+Decide surfaces use color to focus proof, action, reassurance, and risk.
+
+Explore surfaces use color for category, active filters, map clusters, and reversible paths.
+
+I do not spread accent color evenly because the composition feels empty.
+
+---
+
+## System Bar
+
+`/design recolor` creates or repairs a color system. It is not an accent swap.
+
+At minimum, I define and apply roles for canvas, surface, text, muted text, border, primary action, secondary action, focus, selection, success, warning, error, disabled, and any domain-specific status colors.
+
+I verify that real components use the roles: navigation, hero or page header, body content, controls, cards or panels, forms, states, and at least one edge case.
+
+Changing one button color, adding a gradient, or darkening the background is not enough unless the user explicitly asked for that one change.
+
+---
+
+## What I Decide First
+
+I decide the emotional arc before I decide the hue.
+
+- Arrival: what the user feels before reading
+- Decision: what needs the strongest signal
+- Completion: what confirms progress or relief
+- Risk: where danger, loss, or uncertainty appears
+- Rest: where the eye gets to stop working
+
+If the palette does not support that arc, the colors are decorative. I replace them.
+
+---
+
+## My Color Space
+
+I build fresh palettes in OKLCH. I do this because lightness has to behave visually, not mathematically. Equal lightness moves should look equal. HSL cannot promise that.
+
+I keep chroma under control at the extremes. Near-white high chroma fluoresces. Near-black high chroma muddies. The middle of a scale can carry more color; the ends need restraint.
+
+I tint neutrals toward the brand hue. Pure gray goes cold next to color. A tiny hue cast makes surfaces feel related without shouting.
+
+---
+
+## Palette Strategies
+
+I choose the strategy by intent.
+
+**Whisper** means neutrals carry the surface and one accent carries action. Product UI starts here. The accent stays rare enough to mean something.
+
+**Statement** means one color owns a large part of the surface. Brand work often belongs here. If the color is the voice, I let it speak.
+
+**Conversation** means several named roles, each with a job. Campaigns, editorial systems, and data-rich surfaces can use this. I avoid decorative extras with no role.
+
+**Flood** means the surface is the color. Hero moments, capsule pages, launch pages, and art-directed sections can earn this. Product chrome almost never does.
+
+---
+
+## What I Refuse
+
+- Indigo or blue-purple because the brief says tech
+- Cyan accent on neutral SaaS because it feels safe
+- Indigo-to-violet gradients on CTAs
+- Color used only because a component needed "visual interest"
+- Calling a one-off accent change a recolor pass
+- Adding decorative gradients without semantic color roles
+- Red and green as the only difference between states
+- Pure black, pure white, or pure gray as a lazy default
+- Accent color spread across everything
+- Dark mode made by inversion
+- Transparency used because the palette is unfinished
+
+---
+
+## Contrast Is Not Optional
+
+I check contrast as a design material, not as a late compliance pass.
+
+Body text must be comfortably readable. UI components and icons must remain visible. Placeholder text still counts. Text over images needs a stable backing treatment, not hope.
+
+I never let color carry meaning alone. State needs shape, label, icon, position, or motion support.
+
+---
+
+## The Grey Test
+
+I mentally strip every hue to gray. The hierarchy must survive.
+
+If primary, secondary, and accent collapse into the same value, the palette fails for color-blind users and for tired users in bad lighting. I separate lightness before I add more hue.
+
+---
+
+## Dark Mode
+
+Dark mode is a second theme. It is not light mode with the lights off.
+
+Depth comes from surface lightness, not heavy shadow. Accents lose a little chroma so they do not glow. Borders become subtle light, often with a trace of brand hue. Light text needs careful weight because it reads heavier and brighter than dark text.
+
+---
+
+## Domain Default Trap
+
+I ask whether the palette could be guessed from the domain.
+
+A legal platform does not have to be navy and serif. A developer tool does not have to be dark with a terminal font. A logistics product does not have to be yellow and utilitarian. A health app does not have to be white and calm blue.
+
+If the palette is the first idea anyone would expect, I change the scene sentence before I change the swatches.
+
+---
+
+## How I Know Color Is Working
+
+- The palette is applied to real UI, not only declared
+- Semantic roles cover actions, text, surfaces, borders, focus, and states
+- The dominant color is memorable for the right reason
+- The primary action is obvious without being loud everywhere
+- Neutrals feel related to the brand
+- State colors are consistent and learnable
+- The design still reads in grayscale
+- Color blindness simulation keeps primary roles distinct
+- Dark mode feels authored, not inverted
+- The palette does not smell like a generated SaaS template
+
+STRICT RULE — NEVER BREAK THIS
+Do not create report.md, any kind of report, summary, analysis file,
+or extra documentation. This applies every time this file is used.
+Generate no reports unless explicitly asked.