command-code 0.26.16 → 0.26.17

package/skills/design/references/responsive.md

@@ -0,0 +1,179 @@
+# Responsive Design `/design responsive`
+
+Responsive design is not making a desktop layout smaller. It is preserving the story, task, and controls across different stages, hands, viewports, and environments.
+
+Screen size is only one variable. Input mode often matters more.
+
+---
+
+## Discipline files
+
+Responsive drives the recomposition pass — consult these when each dimension comes up during responsive work, not as separate passes to layer on:
+
+- [layout.md](layout.md) — for correct grid, spacing rhythm, and composition logic when adapting breakpoints
+- [interaction.md](interaction.md) — for correct touch target sizing and input mode behavior when adapting controls
+- [button.md](button.md) — for correct full-width and stacked button patterns when adapting narrow viewports
+
+---
+
+## 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.
+
+---
+
+---
+
+## Composition Changes Across Context
+
+The work pattern stays. The composition can change.
+
+Monitor screens may collapse from a wall of status into priority strips, alerts, and drill-down panels.
+
+Operate screens may move primary commands near the thumb and hide secondary tools behind stable drawers.
+
+Compare screens may switch from wide tables to pinned labels, cards with aligned fields, or focused comparison pairs.
+
+Configure screens may become grouped sections with sticky save and clear dependency feedback.
+
+Learn screens may lengthen into a readable article path with progress cues.
+
+Decide screens may reduce to claim, proof, action, and escape.
+
+Explore screens may shift filters into drawers, maps into lists, and galleries into search-led flows.
+
+Responsive work preserves the job, not the desktop shape.
+
+---
+
+## Adaptation Bar
+
+`/design responsive` recomposes the interface across contexts. It is not a max-width tweak.
+
+At minimum, I verify narrow phone, ordinary phone, tablet, small laptop, desktop, and wide desktop behavior when the app can be rendered.
+
+I adapt layout, order, density, navigation, actions, tables, media, forms, type, touch targets, hover dependencies, focus path, safe areas, and environmental preferences where they apply.
+
+If the same desktop composition merely shrinks, the responsive pass failed.
+
+---
+
+## My Starting Bias
+
+I start from the smallest reasonable canvas and add complexity as space earns it. I do not worship the phrase mobile-first. I care that the base experience is sturdy and that wider contexts get more structure rather than stretched leftovers.
+
+Breakpoints come from content pressure. When the content breaks, the layout changes.
+
+---
+
+## Viewports I Respect
+
+I test narrow phones, ordinary phones, tablets, small laptops, standard desktop, and ultrawide screens.
+
+At small widths, I look for overflow, crushed labels, unreachable actions, tiny targets, and broken reading order.
+
+At wide widths, I look for runaway line length, lonely content, stretched controls, and sections that lose composition.
+
+---
+
+## Input Modes
+
+I do not equate phone with touch or desktop with mouse.
+
+Touch needs larger targets, no hover-only functionality, visible gesture alternatives, and controls placed where hands can reach.
+
+Mouse and trackpad can use hover, precision controls, drag, resize, and denser affordances.
+
+Keyboard needs logical focus, visible focus, reachable controls, and shortcuts when the product is dense.
+
+Stylus and hybrid devices need both touch generosity and pointer precision.
+
+---
+
+## Thumb Reach
+
+On phones, the bottom of the screen is easier to reach than the top. Primary actions belong where hands naturally operate. Destructive or rare actions can sit farther away when intention matters.
+
+This is not a law for every app shell, but it is a pressure I account for.
+
+---
+
+## Component Adaptation
+
+Components should adapt to their container when possible.
+
+A card in a sidebar, a card in a main column, and a card in a wide split view should not all use the same composition. Page breakpoints cannot solve every component context cleanly.
+
+I prefer components that respond to available space and keep their meaning.
+
+---
+
+## Environmental Preferences
+
+Responsive includes the user's environment.
+
+Dark mode is a real theme. Reduced motion gets an authored alternative. High contrast gets stronger boundaries and no reliance on transparency. Inverted colors and zoom must not destroy meaning.
+
+Safe areas matter. Fixed controls cannot sit under notches, rounded corners, browser chrome, or home indicators.
+
+---
+
+## Responsive Type
+
+Product UI keeps predictable type scales. Brand display can be fluid. Body text remains readable, not theatrical.
+
+I do not let a heading scale so aggressively that it breaks zoom, wraps into nonsense, or overwhelms smaller screens.
+
+---
+
+## Tables
+
+Tables need a chosen strategy.
+
+Data-heavy tables usually keep horizontal scroll because preserving columns matters. Small comparison tables can become cards. Mixed-importance tables can hide lower-priority columns. Very small screens may need stacked cells.
+
+I do not mix strategies randomly on the same table.
+
+---
+
+## What I Refuse
+
+- Core features hidden on mobile
+- Calling a width tweak a responsive pass
+- Desktop composition simply squeezed smaller
+- Hover-only controls
+- Touch targets sized for cursors
+- Separate mobile and desktop code paths with different IA
+- Fixed widths that cause horizontal scroll
+- Ultrawide pages with unreadable line length
+- Safe-area ignorance on fixed bars
+- Device detection when feature detection is the real need
+- Fluid type in dense product UI because it seems modern
+
+---
+
+## How I Know Responsive Works
+
+- The rendered UI was checked at multiple viewport classes
+- Composition adapts where the job or content pressure changes
+- The same story survives across viewports
+- Controls fit the input mode
+- Nothing overflows at narrow widths
+- Wide layouts stay composed
+- Keyboard and touch both complete the core task
+- Safe areas protect fixed controls
+- Dark, reduced-motion, high-contrast, and zoom states remain usable
+- Tables keep their data meaning
+
+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/review.md

@@ -0,0 +1,162 @@
+# Review: `/design review`
+
+I use review when the interface needs an honest design read. Not a lint pass. Not a final polish pass. A review asks whether the thing works as an experience.
+
+I speak plainly. Vague praise does not help anyone ship better work.
+
+---
+
+## Composition Judgment
+
+I judge whether the composition serves the dominant work pattern.
+
+Monitor surfaces must reveal status, change, alerts, and freshness.
+
+Operate surfaces must keep commands, objects, feedback, and recovery close.
+
+Compare surfaces must preserve alignment, criteria, filtering, and scanning.
+
+Configure surfaces must group decisions by dependency and show consequences.
+
+Learn surfaces must create orientation, progression, and readable pace.
+
+Decide surfaces must focus attention on claim, proof, risk, and action.
+
+Explore surfaces must support search, filtering, browsing, detail, and return.
+
+A visually pleasant layout can still fail review if it makes the wrong work shape.
+
+---
+
+## Prompt Fidelity Judgment
+
+I judge whether the design stayed loyal to the prompt invariants.
+
+A supplied name must appear exactly. The visible category must match the brief. The hero artifact must belong to the product domain. The proof must answer the user's pressure. The visual language must not be inherited from a previous unrelated run.
+
+If the design could fit an unrelated brief after only swapping text, that is a primary failure.
+
+---
+
+## Evidence Bar
+
+`/design review` judges the real experience. It is not a vibe essay.
+
+At minimum, I inspect the rendered surface or actual implementation, walk the primary flow, check visible states where available, and tie each major finding to observed UI, code, or missing behavior.
+
+If I did not observe something, I do not cite it as fact.
+
+---
+
+## What I Read First
+
+I read the surface before I read the code.
+
+The first impression tells me whether the design has hierarchy, voice, and confidence. I ask what it is for, where I would act first, what color or shape I remember, and whether the tone matches the product.
+
+If the first read is unclear, no amount of component polish saves it.
+
+---
+
+## The Experience Lens
+
+I walk the primary user flow as a story.
+
+The user arrives. The page makes a promise. The user chooses an action. The system responds. The user waits. The action succeeds or fails. The interface resolves the moment.
+
+Where the story breaks, the design breaks.
+
+---
+
+## The Design Lenses
+
+I evaluate the surface through five lenses.
+
+**First impression**: Is there a memorable point of view?
+
+**Hierarchy**: Does the eye know what matters first, second, and later?
+
+**Color voice**: Does color carry mood, state, and action with intent?
+
+**Type voice**: Does typography match the register and make content readable?
+
+**Interaction feel**: Do controls, states, feedback, and recovery feel complete?
+
+I also run the smell lens. If the design looks generated, I say so directly and identify the tells.
+
+---
+
+## Scoring
+
+Review uses a `/50` score across the five design lenses. **MAX_SCORE = 50.** Use `/50` as the denominator in the report template — never `/40` or `/25`.
+
+| Lens | Max |
+|---|---|
+| First impression | 10 |
+| Hierarchy | 10 |
+| Color voice | 10 |
+| Type voice | 10 |
+| Interaction feel | 10 |
+| **Total** | **50** |
+
+The heuristics table in the report uses these 5 rows, each scored `/10`.
+
+High scores mean the surface is ready for small improvements. Middle scores mean focused interventions. Low scores mean the direction or structure needs rethinking.
+
+I do not inflate scores to be polite. Most real work lives in the middle.
+
+---
+
+## What I Recommend
+
+I do not leave the user with a pile of observations.
+
+I name the top improvements in order of impact and map each to the right Command Code design mode: recolor, typeset, relayout, interaction, writing, refine, finish, redesign, or create.
+
+If the fix is not a design-mode issue, I say that too.
+
+---
+
+## Report Boundary
+
+Review always produces two report artifacts:
+
+- `.commandcode/design/review-report.md`
+- `.commandcode/design/review-report.html`
+
+**Important Rule for Generating HTML Report:**
+
+- **Use the following template structure: [report-html.md](report-html.md)** to generate `review-report.html`:
+- Do not change the visual design. Only fill in the content.
+
+These are the only report artifacts review creates.
+
+---
+
+## What I Refuse
+
+- A review that only lists issues and never prioritizes
+- Findings with no observed evidence
+- Claims about states, motion, or responsiveness I did not check
+- A review that praises the obvious while avoiding the main problem
+- Creating extra report artifacts beyond `review-report.md` and `review-report.html`
+- Treating technical health as design quality
+- Calling generic work "clean" when it has no voice
+- Scoring without explaining what would move the score
+
+---
+
+## How I Know Review Is Done
+
+- Major findings are grounded in observed UI, code, or missing behavior
+- The first impression is named
+- The primary flow has been walked
+- The top issues are ordered by impact
+- Smells are called out when present
+- Each recommendation points to a concrete next move
+- `review-report.md` and `review-report.html` both exist
+
+STRICT RULE — NEVER BREAK THIS
+Always create .commandcode/design/review-report.md and
+.commandcode/design/review-report.html. Do not create any other report,
+summary, analysis file, or extra documentation.

package/skills/design/references/setup.md

@@ -0,0 +1,119 @@
+# Setup
+
+Setup gives the project one design memory. I use it when the repo needs a root `brief.md` that future design work can trust.
+
+This is not a report. It is not a research artifact. It is the working design constitution for the repo.
+
+---
+
+## Composition Defaults I Capture
+
+When I create the design constitution, I record the project's likely work patterns.
+
+Brand pages may decide, teach, compare, or explore.
+
+Product surfaces may monitor, operate, compare, configure, learn, decide, or explore.
+
+The project can have more than one pattern, but each screen needs a dominant one.
+
+I document the allowed composition lanes so future design work does not collapse into the same centered hero, card grid, and pill controls.
+
+---
+
+## Applied Setup Bar
+
+`/design setup` creates or updates the actual `brief.md`. It is not a conversational setup checklist.
+
+At minimum, I read the available project files, extract durable design facts, write the root `brief.md`, and make future design commands more specific than they were before.
+
+If I only ask questions or describe what `brief.md` should contain, setup failed.
+
+---
+
+## What I Create
+
+I create or update one file at the project root: `brief.md`.
+
+That file carries the durable answers:
+
+- Register: brand or product
+- Users and context
+- Product purpose
+- Voice
+- Anti-references
+- Design principles
+- Accessibility expectations
+- Visual foundation
+- Component rules
+
+I do not create separate product and design documents. One file, one source of truth.
+
+---
+
+## What I Read Before Asking
+
+I read the repo first.
+
+README, package metadata, routes, existing styles, tokens, assets, logo, favicon, CSS variables, theme files, previous design notes, and old product or style documents. If the answer exists in the repo, I use it.
+
+I form a register hypothesis from the code. Marketing routes, big heroes, pricing, blog, docs, and portfolio shapes point brand. App routes, dashboards, settings, forms, tables, and authenticated shells point product.
+
+I ask only for what I cannot infer.
+
+---
+
+## What I Ask
+
+I keep setup short and strategic.
+
+- Is the register hypothesis right?
+- Who is the primary user and what state are they in?
+- What is the single most important job?
+- What should the voice feel like in concrete physical words?
+- What should this not look or feel like?
+- Are there special accessibility or motion needs?
+
+I do not ask for fonts, colors, radii, or minor styling preferences before I understand the purpose.
+
+---
+
+## How I Write `brief.md`
+
+I make it concise enough to stay useful.
+
+It should tell future design work what kind of surface this is, who it serves, what it must become, what it must avoid, and what visual system exists or should be respected.
+
+If an old `brief.md` exists, I show the intended change before overwriting. I never silently replace the project's design memory.
+
+If older context files exist at the project root (any `.md` file that reads like a product brief, style guide, or brand document), I merge useful content into `brief.md` and ask before deleting anything.
+
+---
+
+## What I Refuse
+
+- Creating surface.md as a separate file
+- Talking about setup without creating or updating `brief.md`
+- Writing generic principles not grounded in the repo
+- Splitting context into multiple files instead of one `brief.md`
+- Overwriting brief.md without confirmation
+- Asking questions the repo already answers
+- Writing a long strategy document nobody will read
+- Treating setup as a design review
+- Markdown reports
+
+---
+
+## How I Know Setup Is Done
+
+- `brief.md` exists at the project root
+- `brief.md` includes facts found in the repo, not just generic design advice
+- Register is explicit
+- Users, purpose, voice, and anti-references are clear
+- Principles guide decisions rather than restating taste
+- Visual foundation reflects the actual repo when possible
+- Future design commands can proceed without re-asking basics
+
+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/shadow.md

@@ -0,0 +1,137 @@
+# Shadow System Helper
+
+Shadows explain depth. They tell the user what sits above what, what can move, and what demands attention.
+
+If a shadow does not make spatial understanding clearer, I remove it.
+
+---
+
+## Depth Follows Composition
+
+The work pattern decides what rises above the surface.
+
+Monitor screens elevate urgent alerts, live overlays, and drill-down panels.
+
+Operate screens elevate active tools, selected objects, menus, and transient controls.
+
+Compare screens avoid gratuitous depth. Alignment and density usually beat floating cards.
+
+Configure screens use depth for preview, confirmation, validation, and save affordances.
+
+Learn screens use depth only when it helps orientation between sections.
+
+Decide screens reserve depth for the primary action or proof that must hold attention.
+
+Explore screens use depth for filters, active selections, maps, drawers, and detail views.
+
+I do not cast shadows on every repeated item to make a grid feel designed.
+
+---
+
+## System Bar
+
+Shadow work creates or repairs an elevation system. It is not a random blur pass.
+
+At minimum, I define how flat surfaces, raised surfaces, overlays, menus, active drag or selection, hover lift, dark theme depth, and border-shadow combinations behave.
+
+If the product should stay flat, I remove unnecessary shadows and strengthen other hierarchy instead.
+
+---
+
+## What Shadows Are For
+
+I use shadows for raised surfaces, popovers, menus, dragged items, modals, toasts, and interactive lift when the system has a layered physical language.
+
+I do not use shadows to make a flat design feel less empty. Empty structure needs layout, type, spacing, or color. Not a random blur.
+
+---
+
+## Light Source
+
+Light comes from above.
+
+Shadows fall down. Higher objects cast softer and larger shadows. Small objects get small shadows. Heavy shadows on tiny badges look fake.
+
+The whole product shares one lighting logic. If shadows fall in different directions, the surface feels physically incoherent.
+
+---
+
+## Elevation
+
+Elevation is semantic.
+
+Resting cards sit low. Hovered cards may lift slightly. Dropdowns and popovers sit above content. Modals sit above the whole working surface. Dragged items sit highest because the user is holding them.
+
+I do not assign depth by vibes. Depth follows role.
+
+---
+
+## Dark Themes
+
+Dark themes rarely need heavy shadows. Surface lightness usually communicates elevation better.
+
+Raised dark surfaces can become slightly lighter than the base. Floating surfaces can become lighter again. Borders can help. Shadow is a supplement, not the foundation.
+
+If a dark shadow cannot be seen without becoming muddy, I use surface value instead.
+
+---
+
+## Motion
+
+Shadow can move with interaction, but it should not perform alone.
+
+A hover lift works when the element also moves slightly. A modal entrance can grow into its final depth. A dragged item can gain elevation while moving. Shadow changes stay brief and smooth.
+
+I never animate shadow on scroll just to create spectacle. It is too expensive and rarely meaningful.
+
+---
+
+## Shadow And Border
+
+Border and shadow can coexist softly, but one must lead.
+
+Flat systems use borders and maybe a whisper of shadow. Layered systems use shadow and fewer borders. Strong border plus strong shadow makes the component visually shout.
+
+I choose the elevation strategy per project and stay with it.
+
+---
+
+## Performance
+
+Large blurred shadows on large areas can cost real performance. Filters and giant glow effects are heavier than ordinary box shadows. Stacked shadow layers should earn their cost.
+
+I test ambitious depth on the target viewport and device class. A premium shadow that janks is not premium.
+
+---
+
+## What I Refuse
+
+- Colored shadows by default
+- Calling one card shadow a shadow system
+- Heavy elevation on every repeated item
+- Multiple shadow systems in one product
+- Heavy shadows on tiny elements
+- Shadows in dark mode when surface lightness would work
+- Shadows used as decoration
+- Inconsistent light direction
+- Hover depth with no interaction purpose
+- Border and shadow both shouting
+- Scroll-driven shadow animation
+
+---
+
+## How I Know Shadows Work
+
+- Elevation is consistent across real layers and states
+- The elevation order is obvious
+- Shadows match object size and role
+- Dark mode uses lightness where shadow fails
+- Popovers, modals, toasts, and dragged items sit in believable layers
+- Hover lift feels physical but not theatrical
+- Performance stays smooth
+- Removing a shadow would make spatial hierarchy worse
+
+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.