command-code 0.26.16 → 0.26.17

package/skills/design/references/voice.md

@@ -0,0 +1,183 @@
+# Voice `/design voice`
+
+Brand surfaces are judged before they are understood. A visitor arrives half-ready to leave. The page has to earn the next second.
+
+Here, design is not serving a task. The design is the product.
+
+---
+
+## Discipline files
+
+Voice drives the brand identity pass — consult these when each dimension comes up, not as additional work to run on top:
+
+- [color.md](color.md) — for correct palette construction when committing to a brand hue
+- [typeset.md](typeset.md) — for correct type hierarchy when building the brand voice and display scale
+- [motion.md](motion.md) — for correct timing and personality when adding expressive animation
+- [border.md](border.md) — for correct edge language when choosing frame and art-direction treatments
+- [shadow.md](shadow.md) — for correct depth model when adding atmospheric lighting or elevation
+
+---
+
+## Composition Starts With The Visitor's Job
+
+A brand surface still has work to do.
+
+If the visitor must decide, I narrow the page around claim, proof, trust, and action.
+
+If the visitor must learn, I build editorial flow with strong pacing and readable depth.
+
+If the visitor must explore, I make product paths, examples, filters, or galleries feel open and reversible.
+
+If the visitor must compare, I make differences visible with matrices, side-by-side proof, or ranked value.
+
+If the visitor must believe, I lead with evidence, artifact, image, and specificity before ornament.
+
+The brand voice changes the skin. The visitor's job chooses the composition.
+
+---
+
+## Prompt Invariants Are Sacred
+
+If the prompt supplies a name, that name is the brand. I do not replace it with a smoother, shorter, more familiar, or previously used name.
+
+The first viewport must prove this is the named thing. Logo, headline, artifact, copy, and call to action all belong to the current name, category, user, and job.
+
+I do not let old examples, earlier outputs, familiar startup tropes, or category clichés rename the product or choose the artifact.
+
+---
+
+## Landing Pages Need A Specific Proof Object
+
+A landing page is not complete because it has a headline and an abstract product panel.
+
+I choose one proof object the visitor can inspect. It must come from the actual product world: a domain object, transaction, path, record, environment, comparison, transformation, or workflow that would be recognizable to the intended user.
+
+That proof object drives the composition. It is not decoration beside the headline.
+
+---
+
+## Application Bar
+
+`/design voice` applies brand character across the visible surface. It is not a small garnish pass.
+
+At minimum, I verify the first viewport, proof object, headline voice, type choice, color behavior, CTA language, imagery or artifact treatment, and one memorable brand-specific detail.
+
+Adding a tiny logo mark, accent square, decorative pattern, or one hover flourish is not enough.
+
+---
+
+## The Register
+
+I use this file for marketing pages, landing pages, campaign pages, portfolios, about pages, product stories, and long-form surfaces where impression is the work.
+
+Brand does not mean one aesthetic. A developer tool, hotel, restaurant, gallery, album page, studio portfolio, and consumer product all live here. They need different lanes.
+
+I name the lane before I design.
+
+- Editorial, cultural, luxury
+- Technical, developer, systems-minded
+- Consumer, lifestyle, tactile
+- Studio, portfolio, experimental
+- Campaign, launch, moment-driven
+
+If I cannot name the lane in one sentence, the surface is not ready.
+
+---
+
+## The First 1.5 Seconds
+
+The first viewport must commit.
+
+The user should quickly know the category, feel the voice, and see a reason to continue. Average is not neutral anymore. Average reads generated.
+
+Restraint is allowed only when it is visibly chosen. Timid restraint is absence.
+
+---
+
+## Type Carries Voice
+
+I start with physical words, not generic adjectives. Cold, precise, slightly strange. Warm, tactile, hand-stamped. Expensive, slow, cinematic.
+
+Then I pick type that feels like an object from that world. A field guide. A receipt. A gallery label. A club poster. A terminal manual. A bottle label. A children's science kit.
+
+I reject the obvious first pass when it smells like the current AI design pile. A serif is not automatically elegant. Mono is not automatically technical. A rounded sans is not automatically friendly.
+
+---
+
+## Color Must Commit
+
+Brand pages can use more color than product surfaces. Statement, conversation, and flood color levels are welcome when the brief earns them.
+
+I name a real reference before choosing a hue. Unnamed ambition turns beige.
+
+If the brand needs voice, I do not hide behind a neutral page with one safe accent. If the brand needs quiet, I make the quiet exact.
+
+---
+
+## Composition Has To Make A Choice
+
+The centered stack with three feature cards is the default nobody remembers.
+
+I choose a composition with a point of view:
+
+- Asymmetric when the brand needs energy
+- Strict grid when the brand needs rigor
+- Editorial pacing when the story needs breath
+- Full-bleed image when the subject is physical
+- Type-led minimalism when the words are strong enough
+- Section-by-section art direction when the narrative changes register
+
+I do not split the difference. Half-asymmetric looks broken. Half-editorial looks like a costume.
+
+---
+
+## Imagery
+
+If the subject is physical, I ship imagery. Restaurant, hotel, travel, fashion, product, photography, food, craft, hobby, venue, place. No colored rectangle can stand in for the thing itself.
+
+One decisive image beats five filler images. I search for the specific object and situation, not the category. Alt text is part of the brand voice.
+
+Tech and developer brands can be type-led, code-led, or diagram-led. That is a lane, not an excuse to leave the page visually empty.
+
+---
+
+## Motion Permission
+
+Brand can choreograph when choreography deepens the mood.
+
+Slow editorial scroll, a single strong reveal, type that arrives with intention, section transitions that feel like pacing. These can work. Scattered motion on every card does not.
+
+Sometimes the most confident brand motion is none.
+
+---
+
+## What I Refuse
+
+- Mono everywhere because the brief says engineer
+- Calling tiny decorative touches a brand pass
+- Brand moments that cannot be seen in the rendered page
+- Editorial magazine styling on a brand that is not editorial
+- Rounded-square icons above every heading
+- Hero plus three identical cards as the whole concept
+- A palette that is guessable from the category
+- Zero imagery for a physical subject
+- A font chosen because it appeared in the last generated landing page
+- Motion that exists only to make the page feel less empty
+
+---
+
+## How I Know The Brand Surface Works
+
+- Brand character is visible before I explain it
+- The proof object belongs to this product and drives the page
+- The first viewport has a recognizable point of view
+- The lane fits the subject
+- Type, color, image, and layout sound like the same brand
+- The page would be remembered after two seconds
+- It does not look like the median generated landing page
+- The visitor has a reason to scroll
+
+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/writing.md

@@ -0,0 +1,152 @@
+# UX Writing `/design writing`
+
+Words are interface. They label actions, lower anxiety, explain failures, and make the system feel honest.
+
+I write like the product knows what it is doing.
+
+---
+
+## Writing Follows Composition
+
+The work pattern decides which words matter most.
+
+Monitor writing names status, freshness, severity, and next attention.
+
+Operate writing names commands, object state, immediate feedback, and recovery.
+
+Compare writing names criteria, differences, ranking, and filters.
+
+Configure writing names settings, dependencies, validation, preview, and commit.
+
+Learn writing names progress, orientation, examples, and completion.
+
+Decide writing names claim, proof, risk, trust, and the action.
+
+Explore writing names search, filter, category, result, and reset.
+
+I do not write generic card subtitles to fill a grid. Copy earns its place by helping the work.
+
+---
+
+## Application Bar
+
+`/design writing` rewrites interface copy in place. It is not advice about copy.
+
+At minimum, I inspect buttons, navigation, headings, labels, helper text, empty states, loading states, success states, errors, destructive moments, links, alt text, and repeated terminology where they exist.
+
+If I only rewrite a headline or tagline while operational copy remains vague, the writing pass failed.
+
+---
+
+## Buttons
+
+A button names the action it performs.
+
+I use a clear verb and, when needed, a clear object: save changes, delete project, create account, send invite. I avoid vague permission words like OK, Yes, Submit, Continue, and Learn more unless the destination or outcome is already explicit.
+
+For destructive actions, I name the destruction. If five items will be deleted, the button says that.
+
+---
+
+## Errors
+
+An error is a recovery path, not a scolding.
+
+It should tell the user what happened, why it happened when that helps, and what to do next. It keeps their input. It appears where the fix can happen. It does not blame the user.
+
+I do not make errors cute. Frustrated users need help, not personality theater.
+
+---
+
+## Empty States
+
+An empty state should teach the space.
+
+It says what belongs there, why it matters, and what action fills it. Search empties suggest a different query or clearing filters. First-use empties guide setup. Permission empties explain access. Error empties offer recovery.
+
+"No items" is almost never enough.
+
+---
+
+## Loading
+
+Loading copy names the work being done.
+
+Saving, uploading, analyzing, syncing, importing, checking. If the duration is knowable, I set an expectation. If progress is measurable, I show it. If the wait is long, I give useful context rather than filler.
+
+I avoid generic machine-flavored jokes. Specific beats cute.
+
+---
+
+## Success
+
+Success copy confirms the action and then gets out of the way.
+
+It can add a next implication when useful: password updated, use it next time you sign in. Project created, invite your team. Changes saved. Short, calm, done.
+
+---
+
+## Labels And Help
+
+Labels stay visible. Placeholders show examples or formats. Hint text explains why the system asks or what format it expects.
+
+Icon-only controls need accessible names. Link text stands alone. Alt text describes the information the image contributes, not the fact that an image exists.
+
+---
+
+## Voice And Tone
+
+Voice stays consistent. Tone adapts to the moment.
+
+Product UI is direct, calm, specific, and consistent. Brand surfaces can be more expressive, but still concrete. Errors are sober. Success can be warmer. Destructive moments are plain.
+
+I use the same noun for the same concept everywhere. A project does not become a workspace, board, initiative, and file because variety felt nice.
+
+---
+
+## Translation
+
+I leave room for expansion. German and Finnish get longer. Chinese may use fewer characters but not always less width. Word order changes. Plural rules change.
+
+I keep full sentences as translation units. I avoid string fragments that assume English grammar. I avoid abbreviations when clarity matters.
+
+---
+
+## Punctuation
+
+Sentence case is the default. Labels usually do not need periods. Sentences do. Exclamation points are rare. Em dashes do not belong in generated UI copy for this project; I use commas, colons, semicolons, parentheses, or a shorter sentence.
+
+---
+
+## What I Refuse
+
+- OK, Submit, Click here, or vague Learn more
+- Copy advice without applying copy changes
+- Rewriting only marketing text while UI states stay vague
+- Placeholder-only labels
+- "Something went wrong" with no next move
+- Humor in errors
+- Exclamation points as energy
+- Jargon without context
+- Different terms for the same object
+- Redundant intros that restate headings
+- Copy that explains a bad design instead of fixing it
+
+---
+
+## How I Know The Writing Works
+
+- Copy changes are applied in the actual interface
+- Critical states have specific words, not placeholders
+- Every action says what happens
+- Every error helps recovery
+- Every empty state points somewhere useful
+- Loading copy names the actual work
+- Terminology stays consistent
+- The tone fits the user's emotional state
+- Translation will not shatter the layout
+
+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.