@design-intelligence/ghost 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/init-payloads/median/median-tells.md +27 -26
  2. package/dist/init-payloads/{vessel-light/anti-goal.median.md → median/standard.model-defaults.md} +7 -3
  3. package/dist/init-payloads/skeleton/brand.md +7 -3
  4. package/dist/init-payloads/skeleton/context.conversation.md +22 -13
  5. package/dist/init-payloads/skeleton/foundation.color.md +33 -28
  6. package/dist/init-payloads/skeleton/foundation.composition.md +14 -15
  7. package/dist/init-payloads/skeleton/foundation.controls.md +20 -15
  8. package/dist/init-payloads/skeleton/foundation.layout.md +29 -28
  9. package/dist/init-payloads/skeleton/foundation.motion.md +19 -16
  10. package/dist/init-payloads/skeleton/foundation.type.md +32 -28
  11. package/dist/init-payloads/skeleton/foundation.voice.md +13 -11
  12. package/dist/init-payloads/skeleton/glossary.md +33 -21
  13. package/dist/init-payloads/vessel-light/checks/conversation-grammar.md +2 -2
  14. package/dist/init-payloads/vessel-light/checks/median-tells.md +25 -25
  15. package/dist/init-payloads/vessel-light/checks/motion-restraint.md +2 -2
  16. package/dist/init-payloads/vessel-light/checks/relationships.md +4 -4
  17. package/dist/init-payloads/vessel-light/checks/shape-matches-job.md +9 -9
  18. package/dist/init-payloads/vessel-light/checks/values.md +6 -6
  19. package/dist/init-payloads/vessel-light/context.conversation.md +53 -0
  20. package/dist/init-payloads/vessel-light/context.data-density.md +51 -0
  21. package/dist/init-payloads/vessel-light/context.editorial.md +53 -0
  22. package/dist/init-payloads/vessel-light/context.email.md +53 -0
  23. package/dist/init-payloads/vessel-light/foundation.color-roles.md +41 -0
  24. package/dist/init-payloads/vessel-light/foundation.deletion.md +53 -0
  25. package/dist/init-payloads/vessel-light/foundation.hierarchy.md +73 -0
  26. package/dist/init-payloads/vessel-light/{grammar.job.md → foundation.job.md} +39 -28
  27. package/dist/init-payloads/vessel-light/foundation.motion.md +46 -0
  28. package/dist/init-payloads/vessel-light/foundation.palette.md +57 -0
  29. package/dist/init-payloads/vessel-light/foundation.rhythm.md +39 -0
  30. package/dist/init-payloads/vessel-light/foundation.shape.md +39 -0
  31. package/dist/init-payloads/vessel-light/foundation.surfaces.md +45 -0
  32. package/dist/init-payloads/vessel-light/foundation.tells.md +39 -0
  33. package/dist/init-payloads/vessel-light/{signature.temperature.md → foundation.temperature.md} +31 -13
  34. package/dist/init-payloads/vessel-light/{signature.type.md → foundation.type.md} +27 -12
  35. package/dist/init-payloads/vessel-light/glossary.md +27 -30
  36. package/dist/init-payloads/vessel-light/index.md +18 -15
  37. package/dist/scan/check-scaffold.d.ts.map +1 -1
  38. package/dist/scan/check-scaffold.js +25 -3
  39. package/dist/scan/check-scaffold.js.map +1 -1
  40. package/dist/scan/templates.js +4 -4
  41. package/dist/scan/templates.js.map +1 -1
  42. package/dist/skill-bundle/references/ground.md +3 -2
  43. package/dist/skill-bundle/references/nodes.md +29 -6
  44. package/dist/skill-bundle/references/schema.md +5 -0
  45. package/dist/skill-bundle/references/steering-audit.md +2 -2
  46. package/package.json +1 -1
  47. package/dist/init-payloads/vessel-light/anti-goal.tells.md +0 -38
  48. package/dist/init-payloads/vessel-light/grammar.color-roles.md +0 -28
  49. package/dist/init-payloads/vessel-light/grammar.conversation.md +0 -29
  50. package/dist/init-payloads/vessel-light/grammar.deletion.md +0 -35
  51. package/dist/init-payloads/vessel-light/grammar.hierarchy.md +0 -56
  52. package/dist/init-payloads/vessel-light/grammar.motion.md +0 -25
  53. package/dist/init-payloads/vessel-light/grammar.rhythm.md +0 -25
  54. package/dist/init-payloads/vessel-light/grammar.surfaces.md +0 -33
  55. package/dist/init-payloads/vessel-light/register.data-density.md +0 -39
  56. package/dist/init-payloads/vessel-light/register.editorial.md +0 -41
  57. package/dist/init-payloads/vessel-light/register.email.md +0 -43
  58. package/dist/init-payloads/vessel-light/signature.palette.md +0 -45
  59. package/dist/init-payloads/vessel-light/signature.shape.md +0 -27
  60. /package/dist/init-payloads/{median/cliche.median.md → vessel-light/standard.model-defaults.md} +0 -0
@@ -3,45 +3,45 @@ name: Median tells
3
3
  description: Flags the measured defaults of unsteered generation, the deterministic floor, and current model-signature tells — hover-lift, default accents, unprompted dark theme, gradient text, contrast, frequency tells, and per-model signatures.
4
4
  severity: high
5
5
  references:
6
- - cliche.median > Hover-lift
7
- - cliche.median > Indigo accent
8
- - cliche.median > Dark theme
9
- - cliche.median > Gradients
10
- - cliche.median > Glassmorphism
11
- - cliche.median > Side-stripe
12
- - cliche.median > Cream surface
13
- - cliche.median > Chat bubbles
14
- - cliche.median > Stock copy
15
- - cliche.median > Celebration
16
- - cliche.median > Hero metric
17
- - cliche.median > Eyebrow kicker
6
+ - standard.model-defaults > Hover-lift
7
+ - standard.model-defaults > Indigo accent
8
+ - standard.model-defaults > Dark theme
9
+ - standard.model-defaults > Gradients
10
+ - standard.model-defaults > Glassmorphism
11
+ - standard.model-defaults > Side-stripe
12
+ - standard.model-defaults > Cream surface
13
+ - standard.model-defaults > Chat bubbles
14
+ - standard.model-defaults > Stock copy
15
+ - standard.model-defaults > Celebration
16
+ - standard.model-defaults > Hero metric
17
+ - standard.model-defaults > Eyebrow kicker
18
18
  ---
19
19
 
20
20
  These flags target the measured convergence patterns of unsteered model
21
21
  generation, the deterministic floor the median node licenses, and tells
22
22
  specific to individual models. Each is mechanically detectable in a diff.
23
- Pruning a rule from `cliche.median` orphans its paired reference here —
23
+ Pruning a rule from `standard.model-defaults` orphans its paired reference here —
24
24
  `ghost validate` warns; delete the flag and its reference together.
25
25
 
26
26
  Flag `transform` with `translateY` inside a `:hover` rule on cards,
27
27
  buttons, or list items, especially paired with a shadow increase. Hover
28
28
  confirmation in this package is color and background change, not lift.
29
- (`cliche.median > Hover-lift`)
29
+ (`standard.model-defaults > Hover-lift`)
30
30
 
31
31
  Flag accent values in the indigo/blue/purple default family (`#4f46e5`,
32
32
  `#6366f1`, `#2563eb`, `#3b82f6`, `#8b5cf6`, and close neighbors)
33
33
  unless the diff shows the user asked for them. They are model defaults, not
34
- palette members. (`cliche.median > Indigo accent`)
34
+ palette members. (`standard.model-defaults > Indigo accent`)
35
35
 
36
36
  Flag whole-page dark backgrounds when the ask did not request dark mode.
37
37
  Dark surfaces are a declared brand choice or an explicit theme, never an
38
- unprompted default. (`cliche.median > Dark theme`)
38
+ unprompted default. (`standard.model-defaults > Dark theme`)
39
39
 
40
40
  Flag `linear-gradient` or `radial-gradient` as page or section
41
- backgrounds, and gradient-filled buttons. (`cliche.median > Gradients`)
41
+ backgrounds, and gradient-filled buttons. (`standard.model-defaults > Gradients`)
42
42
 
43
43
  Flag `backdrop-filter: blur` used for glassmorphism cards.
44
- (`cliche.median > Glassmorphism`)
44
+ (`standard.model-defaults > Glassmorphism`)
45
45
 
46
46
  Flag `background-clip: text` (with or without the `-webkit-` prefix)
47
47
  paired with a gradient. Emphasis comes from weight or size in a single
@@ -49,14 +49,14 @@ solid color.
49
49
 
50
50
  Flag a thick colored border on one side of an element (`border-left` or a
51
51
  `border-l-*` utility at 2px or more in a non-neutral color) while the
52
- other sides stay thin. (`cliche.median > Side-stripe`)
52
+ other sides stay thin. (`standard.model-defaults > Side-stripe`)
53
53
 
54
54
  Flag warm off-white page backgrounds in the cream/sand/beige band, and token
55
55
  names like `--cream`, `--sand`, `--parchment`, `--linen` introduced
56
- by the diff. (`cliche.median > Cream surface`)
56
+ by the diff. (`standard.model-defaults > Cream surface`)
57
57
 
58
58
  Flag assistant messages rendered as bubbles with initials-circle avatars.
59
- (`cliche.median > Chat bubbles`)
59
+ (`standard.model-defaults > Chat bubbles`)
60
60
 
61
61
  Flag emoji used as icons or imagery in interface chrome. Text labels carry
62
62
  meaning.
@@ -64,16 +64,16 @@ meaning.
64
64
  Flag stock template copy in headings: "Simple, transparent pricing",
65
65
  "Welcome back", and interchangeable-with-a-competitor phrasing. Recommend
66
66
  copy that states what this product specifically does.
67
- (`cliche.median > Stock copy`)
67
+ (`standard.model-defaults > Stock copy`)
68
68
 
69
69
  Flag exclamation-marked success copy, confetti language, and celebratory UI
70
70
  ("You did it!", "Awesome!"). Confirmation is quiet and factual.
71
- (`cliche.median > Celebration`)
71
+ (`standard.model-defaults > Celebration`)
72
72
 
73
73
  Flag the hero-metric template — a big number, small label, and supporting
74
74
  stats as default proof — unless the metric shows real user data. Recommend
75
75
  evidence specific to the product, or nothing.
76
- (`cliche.median > Hero metric`)
76
+ (`standard.model-defaults > Hero metric`)
77
77
 
78
78
  Deterministic floor — licensed by the median node, verified here, never
79
79
  steered in prose:
@@ -95,7 +95,7 @@ Frequency tells — the crime is repetition, not the move (advisory):
95
95
 
96
96
  Flag three or more uppercase, tracked eyebrow kickers above section headings
97
97
  in one page. One named kicker is voice; a kicker on every section is model
98
- grammar. (`cliche.median > Eyebrow kicker`)
98
+ grammar. (`standard.model-defaults > Eyebrow kicker`)
99
99
 
100
100
  Flag five or more em-dashes in body copy in one view.
101
101
 
@@ -108,7 +108,8 @@ Model-signature tells — skip any block whose model did not produce the diff
108
108
  Codex: flag a 1px border paired with a box-shadow of 16px blur or more on
109
109
  the same element — pick a solid border or a tight shadow, not both. Flag
110
110
  border-radius of 32px or more on cards, sections, or inputs unless an
111
- answered shape dial (`signature.shape`) sanctions large radii — then it is
111
+ answered shape foundation (for example, `foundation.shape`) sanctions large
112
+ radii — then it is
112
113
  fidelity, not a tell. Flag 1px linear-gradient grid or repeating-stripe
113
114
  backgrounds used as decoration.
114
115
 
@@ -2,9 +2,13 @@
2
2
  for: Any greenfield visual surface or first-draft copy.
3
3
  ---
4
4
 
5
- This is the model's median, not your brand. Each rule is reject→replace.
6
- Delete every line your brand legitimately violates `ghost validate` will
7
- warn on any check reference the deletion orphans delete the paired flag too.
5
+ Shared defaults: the model's median, not your brand. Every rule below is a
6
+ **Default** a starting position that protects unsteered work from generic
7
+ model behavior, never an obligation. Explicit brand guidance in the cover, a
8
+ foundation, or a matching context may deliberately replace any of them.
9
+ Each rule is reject→replace. Delete every line your brand legitimately
10
+ violates — `ghost validate` will warn on any check reference the deletion
11
+ orphans — delete the paired flag too.
8
12
 
9
13
  These are not aesthetic opinions. Where a count is given, it is the measured
10
14
  convergence of 300 unsteered generations across three frontier models (the
@@ -6,9 +6,8 @@ This cover is unwritten. ghost gather always places this page in an agent's
6
6
  context; that is delivery status, not a claim that every sentence applies to
7
7
  every task. Use it for what cannot be retrieved by task: what this brand is about,
8
8
  in one paragraph, in the brand's own voice. The temperature its words and
9
- motion share. And the refusals only this brand makes — not generic don'ts
10
- (those live in each foundation's misuse list, and the model's cliches live
11
- in the cliche nodes), but the lines this brand alone draws.
9
+ motion share. And the refusals only this brand makes — not generic don'ts,
10
+ but the lines this brand alone draws.
12
11
 
13
12
  Until a human writes it, the working stance is: quiet, precise, content
14
13
  first, decoration never. Treat that as provisional and say so in your
@@ -19,5 +18,10 @@ single element, it belongs in that element's chapter. In a single view, it
19
18
  belongs in the composition foundation. Only across the whole body of work —
20
19
  temperature, density, restraint — it belongs here.
21
20
 
21
+ Generic don'ts do not live here either: element-scoped rejections live in
22
+ each foundation's Never section, and the model's measured defaults live in
23
+ the shared `standard.model-defaults` node. This page holds only the refusals
24
+ this brand alone makes.
25
+
22
26
  The budget is one screen. When this page is real, delete every sentence of
23
27
  scaffolding above — including this one.
@@ -5,20 +5,29 @@ for: Chat threads, agent consoles, and prompt composers.
5
5
  In this context: AI conversation threads, agent consoles, review assistants,
6
6
  and prompt composers. Elsewhere, the defaults hold.
7
7
 
8
+ ## Usage
9
+
8
10
  Conversation UI is not chat cosplay. The assistant speaks on the page
9
- surface as plain text: no bubble, no border, no fill. Wrapping assistant
10
- messages in cards makes the system look defensive and wastes density —
11
- hierarchy comes from prose, spacing, and type.
11
+ surface as plain text hierarchy comes from prose, spacing, and type.
12
+ Wrapping assistant messages in cards makes the system look defensive and
13
+ wastes density. Tool calls are operational evidence, not conversation.
14
+
15
+ ## Rules
12
16
 
13
- User turns are compact muted surfaces aligned right. They mark authorship
14
- without turning the thread into alternating balloons.
17
+ - Assistant turns render as plain text on the page surface: no bubble, no
18
+ border, no fill.
19
+ - User turns are compact muted surfaces aligned right — authorship marked
20
+ without turning the thread into alternating balloons.
21
+ - Tool calls collapse to a labeled one-line summary with status; expand only
22
+ when the user asks, then show mono content inside the disclosed area.
23
+ - The prompt input is one bordered surface. The textarea stays empty of
24
+ controls; attachments, model choice, and send live in a single row below
25
+ it.
26
+ - Stop and send are mutually exclusive states of the same action area.
15
27
 
16
- Tool calls are operational evidence. Collapse them to a labeled one-line
17
- summary with status; expand only when the user asks, then show mono content
18
- inside the disclosed area.
28
+ ## Never
19
29
 
20
- The prompt input is one bordered surface. The textarea stays empty of
21
- controls so writing remains the focus; attachments, model choice, and send
22
- live in a single row below it. There is one primary send action — stop and
23
- send are mutually exclusive states of the same action area, never two
24
- competing primaries.
30
+ - Never wrap assistant messages in cards or bubbles plain text on the
31
+ page surface.
32
+ - Never render two competing primary actions in the composer — stop and
33
+ send share one action area.
@@ -9,34 +9,39 @@ until a human edits or confirms this chapter.
9
9
 
10
10
  Color is assigned by role, not by taste. The roles are the source of truth;
11
11
  raw color values are implementation detail, never product language. If a
12
- container needs a color, it first needs a role: `background`, `foreground`,
13
- `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `border`,
14
- `input`, `ring`, and the status roles.
15
-
16
- The status roles — destructive, success, warning, info — exist only when
17
- meaning demands them. Destructive means destructive or error. Success means
18
- success. None of them are brand accents.
19
-
20
- One view does not perform a color palette. If a status color is present, the
21
- rest of the view stays on the base roles. Richness beyond this comes from a
22
- closed expression set (`--expression-*`), used at the volume the situation
12
+ container needs a color, it first needs a role. Richness beyond the base
13
+ spine comes from a closed expression set, used at the volume the situation
23
14
  allows — a marketing page may turn it up; a settings form stays quiet.
24
15
 
25
- ## Palette
26
-
27
- Open — ask the human; do not freehand. The fixed relationship: a quiet base
28
- spine is the default atmosphere in every medium, and a closed expression set
29
- supplies the rest, its volume set by situation, never by taste. The open
30
- question: what is this brand's base spine, and what are the named hues of
31
- its expression set how many, and which? When the human answers, restate
32
- this section as the brand's current answer and record the values where your
33
- materials live. Until then, proceed with a quiet provisional spine and label
34
- it provisional.
35
-
36
- ## Misuse
37
-
38
- - Status colors never moonlight as atmosphere, in any context.
39
- - Expression never touches what you click. Buttons, inputs, and links stay
40
- on the base roles everywhere. A colored control is a different design
16
+ The status roles exist only when meaning demands them. None of them are
17
+ brand accents.
18
+
19
+ ## Rules
20
+
21
+ - Every colored element uses a named role: `background`, `foreground`,
22
+ `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `border`,
23
+ `input`, `ring`, or a status role.
24
+ - Status roles carry their meaning exactly: destructive means destructive or
25
+ error, success means success, warning warns, info informs.
26
+ - When a status color is present, the rest of the view stays on the base
27
+ roles. One view does not perform a color palette.
28
+ - Expression color comes only from the closed `--expression-*` set, at the
29
+ volume the situation allows.
30
+ - Known gap the palette is unanswered. The fixed relationship: a quiet
31
+ base spine is the default atmosphere in every medium, and a closed
32
+ expression set supplies the rest, its volume set by situation, never by
33
+ taste. The open question: what is this brand's base spine, and what are
34
+ the named hues of its expression set — how many, and which? Ask the human;
35
+ do not invent values. Until answered, proceed with a quiet provisional
36
+ spine and label it provisional. When answered, restate this rule as the
37
+ brand's current answer and record the values where your materials live.
38
+
39
+ ## Never
40
+
41
+ - Never use status colors as atmosphere, in any context — status color
42
+ appears only where its meaning applies.
43
+ - Never put expression color on what you click. Buttons, inputs, and links
44
+ stay on the base roles everywhere; a colored control is a different design
41
45
  system.
42
- - No one-off hex values. If a color has no role, it has no place.
46
+ - Never use a one-off hex value if a color has no role, it has no place;
47
+ give it a role or delete it.
@@ -9,25 +9,24 @@ until a human edits or confirms this chapter.
9
9
 
10
10
  Composition is the layer above layout: layout gives the stacks and gaps;
11
11
  composition decides what dominates, what recedes, and what comes last.
12
+ Primacy comes from scale, position, and space. Actions land last — the user
13
+ reads, then decides.
12
14
 
13
- Every view has exactly one focal point — one element at the largest scale.
14
- If two elements compete for primacy, demote or delete one; never resolve
15
- the tie by making both big.
15
+ ## Rules
16
16
 
17
- One primary action per view: the action the view exists to complete.
18
- Everything else steps down the control ladder (see the controls
19
- foundation). If two buttons both look primary, the composition failed.
17
+ - Every view has exactly one focal point one element at the largest scale.
18
+ If two elements compete for primacy, demote or delete one.
19
+ - One primary action per view: the action the view exists to complete.
20
+ Everything else steps down the control ladder (see the controls
21
+ foundation).
22
+ - Calls to action render at the end of reading order.
23
+ - Separation escalates: whitespace first, then a divider, then a container —
24
+ in that order, never skipping a step.
20
25
 
21
- Actions land last. Calls to action render at the end of reading order —
22
- the user reads, then decides.
26
+ ## Never
23
27
 
24
- Separation escalates: whitespace first, then a divider, then a container
25
- in that order, never skipping a step.
26
-
27
- ## Misuse
28
-
29
- - Never fake a focal point with decoration. Primacy comes from scale,
28
+ - Never fake a focal point with decoration primacy comes from scale,
30
29
  position, and space.
31
30
  - Never promote a second action to primary because something wants
32
- emphasis; step the other one down instead.
31
+ emphasis step the other one down instead.
33
32
  - Never separate with a container when whitespace would do.
@@ -15,18 +15,23 @@ may hold is a composition rule — see the composition foundation: one.
15
15
  Destructive is a meaning, not a rung. It is rare, it names the destructive
16
16
  act directly, and it is never borrowed for urgency, emphasis, or brand heat.
17
17
 
18
- Fields are quiet until active: hairline border, muted placeholder, clear
19
- label, and a focus ring when the user engages. The ring is guidance, not
20
- decoration. Errors state facts next to the field that caused them — never
21
- hidden in modals, toasts, or generic banners when the user needs to fix one
22
- input.
23
-
24
- Controls take the control radius; see the layout foundation for the two
25
- radius roles.
26
-
27
- ## Misuse
28
-
29
- - Never two competing primary buttons.
30
- - Never destructive styling as attention-getting.
31
- - Never expression color on a control — what you click stays on the base
32
- roles everywhere.
18
+ Fields are quiet until active. The focus ring is guidance, not decoration.
19
+
20
+ ## Rules
21
+
22
+ - Every action picks a rung from the five-rung ladder; no invented emphasis
23
+ levels.
24
+ - Fields render with a hairline border, muted placeholder, clear label, and
25
+ a focus ring when the user engages.
26
+ - Errors state facts next to the field that caused them — never hidden in
27
+ modals, toasts, or generic banners when the user needs to fix one input.
28
+ - Controls take the control radius; see the layout foundation for the two
29
+ radius roles.
30
+
31
+ ## Never
32
+
33
+ - Never render two competing primary buttons — step one down the ladder.
34
+ - Never use destructive styling as attention-getting — destructive names a
35
+ destructive act, nothing else.
36
+ - Never put expression color on a control — what you click stays on the
37
+ base roles everywhere.
@@ -8,41 +8,42 @@ until a human edits or confirms this chapter.
8
8
  ## Usage
9
9
 
10
10
  All layout is stacks. Rhythm comes from relationships between siblings, not
11
- from isolated margins pasted onto whichever element was last touched. The
12
- gap steps are exactly five: `--gap-xs` through `--gap-xl`. Choose the gap
13
- that states the relationship; do not tune by single pixels to make a
11
+ from isolated margins pasted onto whichever element was last touched. Choose
12
+ the gap that states the relationship; do not tune by single pixels to make a
14
13
  screenshot pass. The default is column, medium gap. Columns are for almost
15
14
  everything — forms, cards, modal bodies, settings, page sections. Rows are
16
15
  conditional: controls, metadata lines, paired label/value moments. If a row
17
16
  wraps awkwardly, it wanted to be a column.
18
17
 
19
18
  Surface is the only way an element gets a background, border, radius, or
20
- shadow. The vocabulary is closed: role, padding, radius, border, elevation.
21
- The default surface is flat no border, no shadow. We do not outline
22
- everything to prove layout exists.
23
-
24
- The elevation tiers are exactly three: card, popover, modal. Elevation
25
- implies hierarchy — a card sits in flow, a popover floats above it, a modal
26
- interrupts the task. Pick the tier that matches the interaction.
19
+ shadow. The default surface is flat no border, no shadow. We do not
20
+ outline everything to prove layout exists. Elevation implies hierarchy a
21
+ card sits in flow, a popover floats above it, a modal interrupts the task.
27
22
 
28
23
  Borders are structural — inputs and overlays — not decorative frames around
29
24
  ordinary text. Use space, tone, and type hierarchy instead.
30
25
 
31
- ## Radius
32
-
33
- Open ask the human; do not freehand. The fixed relationship: controls and
34
- surfaces carry different radius roles, and the two never swap. Buttons and
35
- inputs take `--radius-control`; cards and containers take
36
- `--radius-surface`. One radius for what you click, one for what contains.
37
- The open question: how round is a control, and how round is a surface? When
38
- answered, restate this section as the brand's current answer. Until then,
39
- choose provisional values and label them.
40
-
41
- ## Misuse
42
-
43
- - No ad-hoc margins between siblings they hide the rhythm. Change the
44
- stack gap or split the stack.
45
- - No custom shadows because a composition feels flat, and no modal gravity
46
- on a routine card. Component shadows belong to the primitives that own
47
- them.
48
- - Never one radius everywhere by reflex.
26
+ ## Rules
27
+
28
+ - The gap steps are exactly five: `--gap-xs` through `--gap-xl`.
29
+ - The surface vocabulary is closed: role, padding, radius, border,
30
+ elevation.
31
+ - The elevation tiers are exactly three: card, popover, modal. Pick the
32
+ tier that matches the interaction.
33
+ - Buttons and inputs take `--radius-control`; cards and containers take
34
+ `--radius-surface`. The two never swap.
35
+ - Known gap — the radius values are unanswered. The fixed relationship: one
36
+ radius for what you click, one for what contains. The open question: how
37
+ round is a control, and how round is a surface? Ask the human; do not
38
+ invent values. Until answered, choose provisional values and label them.
39
+ When answered, restate this rule as the brand's current answer.
40
+
41
+ ## Never
42
+
43
+ - Never add ad-hoc margins between siblings — they hide the rhythm; change
44
+ the stack gap or split the stack.
45
+ - Never add a custom shadow because a composition feels flat, and never give
46
+ modal gravity to a routine card — component shadows belong to the
47
+ primitives that own them.
48
+ - Never apply one radius everywhere by reflex — the control and surface
49
+ roles exist to differ.
@@ -9,29 +9,32 @@ until a human edits or confirms this chapter.
9
9
 
10
10
  Motion is evidence of a state change. It confirms hover, press, reveal,
11
11
  collapse, entrance, exit, and spatial movement. It does not entertain.
12
-
13
- The entire vocabulary is three duration roles and one ease. Fast is for
14
- hover and press. Normal is for reveals, fades, and small state changes. Slow
15
- is reserved for spatial transitions where the user needs to understand
16
- movement. Prefer opacity and small transforms.
12
+ Prefer opacity and small transforms.
17
13
 
18
14
  In editorial and marketing contexts, entrances may be staged — scroll
19
15
  reveals and section transitions are part of editorial rhythm, still built
20
16
  from the three durations and the one ease. In product UI the same staging is
21
17
  decoration.
22
18
 
23
- ## Character
19
+ ## Rules
24
20
 
25
- Open ask the human; do not freehand. Motion and voice share one
26
- temperature: however warm or cool the brand's words are, its movement
27
- matches. See the voice foundation for the other half of this answer. The
28
- open question here: what character does the one ease carry? When answered,
29
- restate this section. Until then, use a quiet standard ease and label it
30
- provisional.
21
+ - The entire vocabulary is three duration roles and one ease.
22
+ - Fast is for hover and press. Normal is for reveals, fades, and small
23
+ state changes. Slow is reserved for spatial transitions where the user
24
+ needs to understand movement.
25
+ - Known gap the ease's character is unanswered. Motion and voice share
26
+ one temperature: however warm or cool the brand's words are, its movement
27
+ matches; see the voice foundation for the other half. The open question:
28
+ what character does the one ease carry? Ask the human; do not invent an
29
+ answer. Until answered, use a quiet standard ease and label it
30
+ provisional. When answered, restate this rule as the brand's current
31
+ answer.
31
32
 
32
- ## Misuse
33
+ ## Never
33
34
 
34
- - Nothing loops except explicit loading states. Decorative pulsing,
35
+ - Never loop anything except explicit loading states decorative pulsing,
35
36
  floating, glowing, and attention-seeking keyframes are off-language.
36
- - No novelty easings because a surface feels static.
37
- - If removing an animation does not reduce comprehension, it was decoration.
37
+ - Never reach for a novelty easing because a surface feels static — fix
38
+ spacing, copy, and hierarchy first.
39
+ - Never keep an animation whose removal would not reduce comprehension — it
40
+ was decoration.
@@ -9,39 +9,43 @@ until a human edits or confirms this chapter.
9
9
 
10
10
  Hierarchy is a closed vocabulary, not a size slider. Every piece of text
11
11
  picks from a named set; anything outside the set is a broken primitive, not
12
- a variant.
12
+ a variant. Variant names are jobs: display leads a rare editorial moment,
13
+ headline names a section, title anchors a card, dialog, or compact region,
14
+ body carries reading, label names structure — field labels, category tags,
15
+ metadata, compact status — and mono carries code and machine detail.
13
16
 
14
- The text variants are exactly six: display, headline, title, body, label,
15
- mono. Variant names are jobs. Display leads a rare editorial moment.
16
- Headline names a section. Title anchors a card, dialog, or compact region.
17
- Body carries reading. Label names structure — field labels, category tags,
18
- metadata, compact status. Mono carries code and machine detail.
19
-
20
- The tones are exactly seven: default, muted, inverse, success, warning,
21
- info, destructive. Tone is part of the message. Hierarchy starts with tone
22
- and weight before size — a secondary note usually wants muted body or label,
23
- not a smaller custom font. If prose needs emphasis, improve the sentence
24
- before adding a style.
17
+ Tone is part of the message. Hierarchy starts with tone and weight before
18
+ size a secondary note usually wants muted body or label, not a smaller
19
+ custom font. If prose needs emphasis, improve the sentence before adding a
20
+ style.
25
21
 
26
22
  The heading scale is editorial: it exists for pages composed outside the
27
23
  text variants — heroes and editorial moments. Product UI never mixes the two
28
24
  vocabularies in one view. A modal title is not a poster.
29
25
 
30
- Balanced text is for headings and compact statements, never long body copy.
31
-
32
- ## Typeface
33
-
34
- Open — ask the human; do not freehand. The fixed relationship: one typeface
35
- is the voice of the interface, everywhere, with a mono partner only for
36
- code, tool detail, and machine output. The open question: what typeface is
37
- this brand's voice, what mono partners it, and what rhythm does the
38
- editorial heading scale carry? When answered, restate this section as the
39
- brand's current answer. Until then, choose a quiet provisional pair and
40
- label it provisional.
26
+ ## Rules
41
27
 
42
- ## Misuse
43
-
44
- - No faked hierarchy with arbitrary font sizes. Choose the variant that
45
- matches the job.
28
+ - The text variants are exactly six: display, headline, title, body, label,
29
+ mono.
30
+ - The tones are exactly seven: default, muted, inverse, success, warning,
31
+ info, destructive.
46
32
  - Status tones appear only when the words carry that state meaning.
47
- - Never a second display face to make a view feel branded.
33
+ - Balanced text is for headings and compact statements, never long body
34
+ copy.
35
+ - Known gap — the typeface is unanswered. The fixed relationship: one
36
+ typeface is the voice of the interface, everywhere, with a mono partner
37
+ only for code, tool detail, and machine output. The open question: what
38
+ typeface is this brand's voice, what mono partners it, and what rhythm
39
+ does the editorial heading scale carry? Ask the human; do not invent
40
+ values. Until answered, choose a quiet provisional pair and label it
41
+ provisional. When answered, restate this rule as the brand's current
42
+ answer.
43
+
44
+ ## Never
45
+
46
+ - Never fake hierarchy with arbitrary font sizes — choose the variant that
47
+ matches the job.
48
+ - Never apply a status tone to words that do not carry that state meaning —
49
+ use default or muted instead.
50
+ - Never add a second display face to make a view feel branded — brand
51
+ expression comes from the one voice, scale, and composition.
@@ -15,18 +15,20 @@ Voice and motion carry the same temperature: a brand whose copy is warm does
15
15
  not move coldly, and a brand whose copy is spare does not bounce. When you
16
16
  set one, check the other.
17
17
 
18
- ## Warmth
18
+ ## Rules
19
19
 
20
- Open ask the human; do not freehand. The open question: how warm or cool
21
- does this brand sound and, by the shared temperature, how does it move?
22
- See the motion foundation for the other half. When answered, restate this
23
- section as the brand's current answer. Until then, write plainly and label
24
- the tone provisional.
20
+ - Error and failure copy states the fact and the next step.
21
+ - Known gapthe warmth is unanswered. The open question: how warm or cool
22
+ does this brand sound and, by the shared temperature, how does it move?
23
+ See the motion foundation for the other half. Ask the human; do not invent
24
+ an answer. Until answered, write plainly and label the tone provisional.
25
+ When answered, restate this rule as the brand's current answer.
25
26
 
26
- ## Misuse
27
+ ## Never
27
28
 
28
- - No exclamation points as a substitute for having something to say.
29
- - No apologizing for the interface ("Oops!"). State the fact and the next
29
+ - Never use exclamation points as a substitute for having something to
30
+ say state the fact.
31
+ - Never apologize for the interface ("Oops!") — state the fact and the next
30
32
  step.
31
- - Never restate this section as answered when it was your own provisional
32
- choice.
33
+ - Never restate an open question as answered when the answer was your own
34
+ provisional choice — label it provisional until a human confirms it.