command-code 0.26.16 → 0.26.17

package/skills/design/references/smell.md

@@ -0,0 +1,197 @@
+# Smell: `/design smell`
+
+I use smell to catch generic design before it spreads. This is not a broad review. It is a detector for reflex, template, and generated sameness.
+
+When a surface smells wrong, I fix the category reflex first. Cosmetic edits do not remove the odor.
+
+---
+
+## Composition Smell
+
+I check whether the composition came from the work or from habit.
+
+Monitor smell: status hidden inside equal cards, alerts without priority, live data treated as static decoration.
+
+Operate smell: tools far from objects, no inspector, no command surface, no fast feedback.
+
+Compare smell: comparison forced into unrelated cards, missing alignment, weak filters, unstable scan paths.
+
+Configure smell: settings scattered by visual balance instead of dependency and consequence.
+
+Learn smell: sections arranged as feature tiles when the user needs a path.
+
+Decide smell: too many equal calls to action, proof buried below ornament.
+
+Explore smell: search, filters, results, and backtracking treated as afterthoughts.
+
+Centered grid is not automatically wrong. It is wrong when it has no work-pattern reason to exist.
+
+---
+
+## Prompt Drift Smell
+
+I treat prompt drift as a severe smell.
+
+Wrong name, recycled logo mark, reused headline structure, inherited proof object, generic visual artifact, and domain objects from an unrelated brief all mean the design is not listening.
+
+The fix is not copy editing. The fix is returning to the current prompt's name, category, user, job, artifact, evidence, and refused drift.
+
+---
+
+## Evidence Bar
+
+`/design smell` names generic design tells from the actual surface. It does not invent odor.
+
+At minimum, I identify the visible pattern, the reflex behind it, why it weakens this specific brief, and the right mode to fix it.
+
+If a smell is only a suspicion, I mark it as a suspicion. I do not report it as observed.
+
+---
+
+## What Smell Means
+
+A smell is a choice that looks unchosen.
+
+It may be competent. It may even be accessible. The problem is that it could have come from any prompt, any template, any average SaaS homepage, any safe default.
+
+I look for the moment where the design stopped making project-specific decisions.
+
+---
+
+## The Odors I Track
+
+**Tech gradient**: blue-violet, indigo-cyan, and purple-to-teal glossy energy plastered on heroes, CTAs, cards, or text. The visual shorthand for "AI startup."
+
+**Generic tech hue**: blue-purple as the primary identity for anything vaguely technical or software-adjacent.
+
+**Feature tile grid**: icon, heading, one sentence, repeated in a uniform grid until the section stops meaning anything. Every card equal, nothing prioritized.
+
+**Accent rail**: a colored stripe on one side of cards or callouts added to simulate structure. Decoration pretending to be organization.
+
+**Unearned blur**: frosted glass panels applied because the surface never committed to a depth system.
+
+**Stat monument**: an oversized number cluster filling space where a real product story belongs.
+
+**Icon topper**: a rounded-square icon placed above every section heading with no function beyond filling the template.
+
+**Bounce everywhere**: motion that turns every interaction into a toy. Elastic easing applied because it was available.
+
+**Default type**: a common family used with no voice, no scale, no reason. The font that appeared because no choice was made.
+
+**Center stack**: everything aligned to the safe middle because no composition decision was made.
+
+---
+
+## The Domain Default Trap
+
+I ask whether the visual direction could be guessed from the industry.
+
+A note-taking app as cream and rounded sans. A developer tool as dark with terminal mono. A health product as white and calm blue. A legal platform as navy and serif. A food app as warm orange. A payments product as clean white with green accents.
+
+If the answer was obvious before I opened the page, the design has not found itself yet.
+
+---
+
+## What I Look For Instead
+
+The design needs at least a few real decisions:
+
+- A color strategy that is not the domain's first reflex
+- Type with a reason
+- A composition that chooses tension, rigor, image, or editorial pacing
+- Imagery or visual material tied to the subject
+- Motion that reveals character or state
+- Copy with a specific voice
+- An interaction or detail that could only belong here
+
+Unexpected is not automatically good. But a page with nothing unexpected is usually forgettable.
+
+---
+
+## How I Judge Severity
+
+I treat faint smells as cleanup. I treat clustered smells as identity failure.
+
+A single generic icon card can be replaced. A whole page made of generic cards, indigo gradients, centered hero, Inter, and vague copy needs a new lane.
+
+If the smell is structural, I do not patch. I change the direction.
+
+---
+
+## What I Do After Finding Smell
+
+I name the dominant smell. I identify the root reflex. Then I pick the right design tool.
+
+- Color reflex goes to recolor
+- Type reflex goes to typeset
+- Composition reflex goes to relayout or redesign
+- Generic brand lane goes to voice or redesign
+- Missing state and interaction smell goes to interaction
+- Unclear copy goes to writing
+
+If the design smells generated in several systems at once, redesign is usually cleaner than incremental repair.
+
+---
+
+## Scoring
+
+Smell uses a `/10` score. The score is **inverted** — finding nothing is perfect.
+
+| Tells found | Score |
+|---|---|
+| 0 | 10/10 — CLEAN |
+| 1–2 | 7–8/10 — FAINT |
+| 3–4 | 5–6/10 — PRESENT |
+| 5–6 | 3–4/10 — STRONG |
+| 7+ | 0–2/10 — IDENTITY FAILURE |
+
+**MAX_SCORE = 10.** Use `/10` as the denominator in the report template. When zero tells are found, the score is `10/10` and the verdict is CLEAN. Never output `0/10` to mean "no smells detected."
+
+The heuristics table in the report uses 10 rows (one per odor tracked). Each row scores `1` if the odor is absent, `0` if detected.
+
+---
+
+## Report Boundary
+
+Smell always produces two report artifacts:
+
+- `.commandcode/design/smell-report.md`
+- `.commandcode/design/smell-report.html`
+
+**Important Rule for Generating HTML Report:**
+
+- **Use the following template structure** [report-html.md](report-html.md) to generate `smell-report.html`:
+- Do not change the visual design. Only fill in the content.
+
+These are the only report artifacts smell creates.
+
+---
+
+## What I Refuse
+
+- Calling a design clean because it passes technical checks
+- Reporting a smell I cannot point to
+- Treating personal taste as evidence of generated design
+- Fixing an AI gradient by choosing a different AI gradient
+- Treating Inter as wrong when it is clearly intentional
+- Treating all centered layouts as bad when symmetry is the right lane
+- Adding decoration to hide generic structure
+- Creating extra report artifacts beyond `smell-report.md` and `smell-report.html`
+
+---
+
+## How I Know The Smell Is Gone
+
+- Every named smell maps to a visible choice
+- The palette cannot be guessed from the domain alone
+- The type has a project-specific reason
+- The composition is not the median generated landing page
+- Repeated sections have hierarchy and variation
+- The strongest visual idea belongs to this brief
+- A stranger would not immediately say the page was generated
+- `smell-report.md` and `smell-report.html` both exist
+
+STRICT RULE — NEVER BREAK THIS
+Always create .commandcode/design/smell-report.md and
+.commandcode/design/smell-report.html. Do not create any other report,
+summary, analysis file, or extra documentation.

package/skills/design/references/surface.md

@@ -0,0 +1,163 @@
+# Surface `/design surface`
+
+Product design serves the work. The user is not here to admire the interface. They are here to finish a task, trust the system, and come back tomorrow without relearning it.
+
+The best product UI becomes familiar faster than it becomes impressive.
+
+---
+
+## Discipline files
+
+Surface drives the product hardening pass — consult these for correct execution when each dimension comes up, not as separate passes to layer on:
+
+- [button.md](button.md) — for correct button states and control hierarchy when hardening interactive elements
+- [interaction.md](interaction.md) — for correct state coverage, keyboard path, and touch targets when auditing component behavior
+- [border.md](border.md) — for correct edge language and surface separation when tightening component boundaries
+- [shadow.md](shadow.md) — for correct elevation decisions when adjusting depth and layering
+- [writing.md](writing.md) — for correct label, error, and empty state copy when hardening operator-facing text
+
+---
+
+## Composition Starts With The Operator's Job
+
+I name the operator's task before choosing structure.
+
+Monitor: expose status, alerts, trends, and freshness.
+
+Operate: keep commands, target objects, and feedback in one working field.
+
+Compare: preserve columns, labels, filters, and scan paths.
+
+Configure: group settings by consequence and show what will change.
+
+Learn: onboard through progressive disclosure without hiding core controls.
+
+Decide: surface proof, risk, tradeoffs, and the next safe action.
+
+Explore: support search, filter, sort, and reversible browsing.
+
+Product composition is not decoration. It is workflow made visible.
+
+---
+
+## Hardening Bar
+
+`/design surface` hardens the working surface. It is not a visual polish pass.
+
+At minimum, I cover the primary task, real data density, focus path, loading, empty, error, success, disabled, overflow, mobile structure, keyboard use, and copy for recovery where those states apply.
+
+If I only changed color, spacing, or type while product states remain missing, the product pass failed.
+
+---
+
+## The Register
+
+I use this file for app UIs, dashboards, admin panels, settings, authenticated routes, tools, tables, forms, editors, and operational screens.
+
+In product, familiarity can be a feature. Surprise has to earn its place.
+
+---
+
+## What Good Feels Like
+
+An experienced operator should open the screen for the eleventh time that day and move without hesitation.
+
+Controls stay where they are expected. Labels use the same nouns. Rows keep stable density. Primary actions are obvious. Secondary actions are reachable but not loud.
+
+If the user pauses because the UI is clever, I made the wrong trade.
+
+---
+
+## Type
+
+I usually pick one strong sans or the system stack. Product labels, tables, settings, and forms do not need display type.
+
+Scale stays compressed. Weight, color, and spacing carry hierarchy with size. Dense surfaces can use smaller type when the audience is skilled and the row structure is clear.
+
+Numbers align. Tables deserve tabular figures. Metadata deserves restraint.
+
+---
+
+## Color
+
+Product color has three jobs.
+
+**Chrome** gives the app stable surfaces: page, sidebar, panel, row, input, divider.
+
+**State** teaches the user the system vocabulary: selected, dirty, focused, loading, success, warning, error, disabled.
+
+**Primary action** gets the strongest accent. If everything is accented, no action is primary.
+
+Product starts restrained. A welcome flow or onboarding moment can carry more color. The working surface gets calmer after login.
+
+---
+
+## Components
+
+Every interactive component needs its real life, not just its resting state.
+
+Default, hover, focus-visible, active, disabled, loading, selected, error, success, empty, overflow. Some components use all of these. Some use fewer. None get to ignore the states they can enter.
+
+Same control, same vocabulary. If two save buttons look unrelated, one is wrong.
+
+---
+
+## Density
+
+Product surfaces breathe less than marketing. Density is not clutter when the relationships are clear.
+
+Rows, panels, filters, toolbars, and tables should fit the work. Power users often need more on screen, not more air. Comfortable and compact modes can be a real feature.
+
+---
+
+## Motion
+
+Product motion is short and functional.
+
+Hover, press, selection, drawer open, popover close, loading, save confirmation. That is enough. No page-load ceremony. No scrolling performance. No animation that delays the task.
+
+---
+
+## What Product Can Own
+
+- System fonts
+- Standard navigation
+- Tables with many rows
+- Predictable sidebars and tabs
+- Keyboard shortcuts
+- Monochrome charts with one emphasized series
+- Dense but organized screens
+- Repetition, when repetition teaches the system
+
+---
+
+## What I Refuse
+
+- Display fonts in labels, tables, or form controls
+- Calling visual polish product hardening
+- Leaving real data, error, empty, loading, or overflow states untested
+- Marketing hero motion inside a working app
+- Custom controls that lose native keyboard behavior
+- Modals for long forms that need a route
+- Five gray scales across one product
+- Accent color on cancel, secondary, decorative, and inactive elements
+- Custom scrollbars that make scrolling harder
+- Cleverness where predictability would build trust
+
+---
+
+## How I Know Product UI Works
+
+- The surface survives real data and real states
+- The primary task is clear without reading instructions
+- Focus, loading, error, empty, and success states exist
+- A keyboard user can complete the core flow
+- Tables and dense data stay aligned and scannable
+- Mobile layout changes structure rather than hiding work
+- The same pattern means the same thing across screens
+- The interface feels calmer the more often it is used
+
+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/tokenize.md

@@ -0,0 +1,124 @@
+# Design System: Tokenize `/design tokenize`
+
+Tokenize turns repeated design decisions into shared language. I extract what has proven itself. I do not invent a system because one component happened to look reusable.
+
+Consolidation, not invention.
+
+---
+
+## Composition Tokens
+
+I tokenize composition only after I understand the work pattern it serves.
+
+Monitor tokens include status strips, alert rows, metric clusters, feed items, and drill-down panels.
+
+Operate tokens include command bars, tool groups, canvases, inspectors, selection states, and feedback surfaces.
+
+Compare tokens include tables, matrices, pinned headers, row actions, bulk controls, and ranking patterns.
+
+Configure tokens include field groups, dependency notes, previews, summaries, and commit bars.
+
+Learn tokens include article sections, progress markers, examples, walkthrough cards, and completion states.
+
+Decide tokens include proof blocks, risk notes, trust markers, and primary action zones.
+
+Explore tokens include filters, chips, result rows, maps, galleries, and detail drawers.
+
+I do not extract a repeated centered-card composition unless it is genuinely the product's language.
+
+---
+
+## Extraction Bar
+
+`/design tokenize` changes the implementation. It is not a naming wishlist.
+
+At minimum, I identify repeated decisions, create or update the reusable tokens/components that belong in the project, migrate at least one real usage when safe, and verify the old behavior still works.
+
+If I only list suggested tokens or component names, tokenizing failed unless the user explicitly asked for planning only.
+
+---
+
+## When I Tokenize
+
+I need repetition with the same intent.
+
+Three repeated components with the same job. Several hard-coded values that mean the same thing. Multiple versions of one control drifting apart. A repeated composition pattern. A repeated behavior, animation, typography style, or state treatment.
+
+Similarity is not enough. Two things that look alike but serve different purposes may need to stay separate.
+
+---
+
+## What I Look For
+
+**Components**: buttons, cards, inputs, modals, rows, badges, tabs, dropdowns, empty states, form fields.
+
+**Tokens**: color roles, spacing roles, radii, shadows, type styles, motion timing, z layers.
+
+**Compositions**: toolbar groups, form rows, page shells, list-detail layouts, table headers, onboarding empties.
+
+**Behavior**: loading patterns, disclosure, keyboard handling, validation, drag, selection, overlay logic.
+
+The best candidates reduce future decisions without hiding important variation.
+
+---
+
+## Naming
+
+I name by meaning, not value.
+
+Primary action, danger text, panel border, section gap, input radius, tooltip layer. These names survive value changes. Names like blue-500 or spacing-16 only help when they are primitives in a larger system.
+
+Semantic names belong where components consume them. Primitive names belong deeper in the foundation.
+
+---
+
+## Component Extraction
+
+I extract the smallest useful API.
+
+The component should match existing project conventions, support the states already needed, keep accessibility built in, and avoid prop sprawl. Variants come from real use, not imagination.
+
+I migrate carefully. Old behavior must survive. Visual regressions are not acceptable payment for abstraction.
+
+---
+
+## Token Extraction
+
+Values become tokens when they represent a reusable decision.
+
+One-off values can stay local. Repeated values with the same meaning become tokens. Repeated values with different meanings should not share a token just because the number matches.
+
+The goal is fewer arbitrary choices in future work.
+
+---
+
+## What I Refuse
+
+- Extracting before a pattern is proven
+- Listing token ideas without applying them
+- Creating unused tokens or components
+- Creating a generic component so flexible it means nothing
+- Tokenizing every number
+- Replacing clear local code with opaque abstraction
+- Breaking existing APIs during migration
+- Ignoring accessibility in extracted controls
+- Creating documentation files as part of tokenizing
+- Markdown reports
+
+---
+
+## How I Know Tokenize Worked
+
+- Tokens or components are actually used by real UI
+- Unused abstractions were not introduced
+- Repetition is reduced without losing intent
+- Names explain roles
+- Components match project conventions
+- States and accessibility are preserved
+- Old duplicate code is removed only after migration is complete
+- Future screens have fewer arbitrary design decisions to make
+
+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/typeset.md

@@ -0,0 +1,170 @@
+# Typography: `/design typeset`
+
+I use type to make thought visible. Fonts are only one part of it. The real work is rhythm, hierarchy, measure, voice, loading behavior, and the tiny details that make reading feel effortless.
+
+Most generic design starts with a default font and a timid scale. I start with the content and the distance from the reader.
+
+---
+
+## Type Follows Composition
+
+The work pattern decides how type behaves.
+
+Monitor screens need labels, deltas, timestamps, thresholds, and compact hierarchy.
+
+Operate screens need tool names, object names, status text, shortcuts, and fast confirmation.
+
+Compare screens need aligned numbers, durable headers, scannable row text, and steady labels.
+
+Configure screens need field labels, helper text, validation, section titles, and summary language.
+
+Learn screens need long-form rhythm, generous measure, clear headings, and progress markers.
+
+Decide screens need a strong claim, proof hierarchy, objections, and one action label.
+
+Explore screens need search language, filters, tags, result titles, and metadata that can be skimmed.
+
+I do not force a marketing type scale onto product work or a product type scale onto brand memory.
+
+---
+
+## System Bar
+
+`/design typeset` creates or repairs a type system. It is not a font-size tweak.
+
+At minimum, I apply readable body text, a clear heading scale, durable labels, button text, form text, metadata, empty/error/loading copy, line-height, measure, weight contrast, and responsive behavior.
+
+If I change fonts, I verify the font is actually loaded or available. A font name in a style value does not count if the browser falls back silently.
+
+Changing only the hero headline or one paragraph is not enough unless the user explicitly asked for that one element.
+
+---
+
+## What Type Must Do
+
+Type has three jobs.
+
+- Make the page understandable at a glance
+- Make the content comfortable to read
+- Give the surface a voice that matches its register
+
+If a type choice does not help one of those jobs, I replace it.
+
+---
+
+## Reading Distance
+
+I do not assume body text is fine because it is a common size. Phone, laptop, monitor, and TV are different reading situations.
+
+Short, close interfaces can run tighter. Large displays and long reading contexts need more size, more line-height, and more controlled measure. Product UI can be dense. Brand display can be loud. Body copy still needs mercy.
+
+---
+
+## Content Length Rules The Measure
+
+I match line-height and width to the text itself.
+
+Microcopy wants tight leading and fast recognition. Short-form text wants two clean lines at most. Paragraphs want a comfortable measure, usually around the classic readable band. Long-form wants more air, not more decoration.
+
+If a paragraph sprawls across the viewport, the layout is asking the reader to do the designer's work.
+
+---
+
+## Font Choice
+
+For brand work, I use the physical-object method. I name the brand as a thing I can hold or see: a museum caption, a club flyer, a diner receipt, a technical manual, a ceramic stamp, a field notebook. Then I pick type that belongs to that object.
+
+I ask whether the font choice carries any project-specific reason. A font that appears in every second launched product signals nothing — it just means the decision was not made. The brand already owns it, or it was the path of least resistance.
+
+That test applies to whatever family is currently over-used. The answer changes over time; the question does not.
+
+For product work, a strong system stack or one well-tuned sans is often the best choice. Product type should help operators move fast. It does not need a costume.
+
+---
+
+## Pairing & Font System
+ 
+Add a second family only when it creates real contrast in structure, proportion, texture, or voice.
+ 
+**The non-obvious truth:** One well-chosen font in multiple weights (Regular, Medium, Semibold, Bold + Italics) creates cleaner hierarchy than two competing faces. Only add a second font when you need genuine contrast.
+ 
+**Bad pairing patterns:**
+- Two similar geometric sans (tension without hierarchy)
+- Fonts that compete for the same visual space
+- A third font with no distinct job
+**The pairing check:**
+- Does the display font differ from body in x-height, stroke contrast, or width?
+- Does each family serve a distinct job (headline vs body vs UI)?
+- Would removing one font break the visual system?
+If any answer is no, use one family with stronger weights instead.
+ 
+**Three-font system (when justified):**
+- **Display/Heading:** Bold personality, high contrast (serif, geometric, custom)
+- **Body/Paragraph:** High readability, moderate x-height, comfortable at small sizes (humanist sans, system stack, text serif)
+- **UI/Badge:** Compact, clear at small sizes, tabular numerals (condensed sans, mono, or body with tighter tracking)
+Use three fonts only when each serves a visibly distinct purpose. Most work is better served by two fonts or one strong family.
+ 
+---
+
+## Hierarchy
+
+Each text block needs a clear chain: hook, bridge, detail. More levels create fog. Fewer levels flatten the message.
+
+Hierarchy can come from size, weight, color, position, spacing, and casing. Size alone is crude. The best systems combine two or three dimensions and keep the rest quiet.
+
+Brand pages can use dramatic jumps. Product surfaces use compressed steps with weight and color doing more of the work.
+
+---
+
+## Dark Surfaces
+
+Light type on dark backgrounds needs compensation. It reads thinner in some ways and brighter in others. I give it more line-height, a touch more spacing when needed, and a weight that feels optically correct.
+
+I test it with real content, not a perfect headline.
+
+---
+
+## Details I Do Not Skip
+
+- Tabular numbers for data, metrics, prices, and aligned values
+- Balanced heading wraps where support exists
+- Better paragraph wraps where support exists
+- Small caps only when the font actually supports them
+- Extra tracking for short all-caps labels
+- No decorative faces for body text
+- No widows, orphaned single words, or ugly rivers in important prose
+- Font loading that avoids obvious layout shift
+
+---
+
+## What I Refuse
+
+- Choosing the first trendy family that fits the category
+- Calling one headline resize a typography pass
+- Naming a font that is not actually loaded or available
+- A flat scale where everything is almost the same size
+- Body text wider than comfortable reading allows
+- All-caps paragraphs
+- Display fonts in product labels
+- A third font with no distinct job
+- Tiny mobile text to preserve a desktop layout
+- Broken fallback metrics that make text jump
+
+---
+
+## How I Know The Type Is Working
+
+- Type changes appear across real content, not only the hero
+- The loaded or available font matches the claimed type choice
+- The primary message reads before the decoration
+- Body text can be read without effort
+- The type voice matches the surface register
+- Numbers align cleanly
+- Headings break with intention
+- The system works with long strings and short labels
+- The page would still feel designed if color disappeared
+
+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.