@design-intelligence/ghost 0.29.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 (142) hide show
  1. package/README.md +2 -2
  2. package/dist/cli.js +2 -2
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands/command-discovery.d.ts.map +1 -1
  5. package/dist/commands/command-discovery.js +10 -3
  6. package/dist/commands/command-discovery.js.map +1 -1
  7. package/dist/commands/gather-command.js +5 -5
  8. package/dist/commands/gather-command.js.map +1 -1
  9. package/dist/commands/init-command.d.ts.map +1 -1
  10. package/dist/commands/init-command.js +2 -2
  11. package/dist/commands/init-command.js.map +1 -1
  12. package/dist/commands/pull-command.d.ts.map +1 -1
  13. package/dist/commands/pull-command.js +8 -7
  14. package/dist/commands/pull-command.js.map +1 -1
  15. package/dist/commands/review-command.d.ts.map +1 -1
  16. package/dist/commands/review-command.js +1 -2
  17. package/dist/commands/review-command.js.map +1 -1
  18. package/dist/commands/stats-command.d.ts +3 -0
  19. package/dist/commands/stats-command.d.ts.map +1 -0
  20. package/dist/commands/{pulse-command.js → stats-command.js} +59 -39
  21. package/dist/commands/stats-command.js.map +1 -0
  22. package/dist/commands/stats-observations.d.ts +10 -0
  23. package/dist/commands/stats-observations.d.ts.map +1 -0
  24. package/dist/commands/stats-observations.js +47 -0
  25. package/dist/commands/stats-observations.js.map +1 -0
  26. package/dist/embed/gather.d.ts.map +1 -1
  27. package/dist/embed/gather.js +3 -4
  28. package/dist/embed/gather.js.map +1 -1
  29. package/dist/embed/pull.d.ts.map +1 -1
  30. package/dist/embed/pull.js +1 -3
  31. package/dist/embed/pull.js.map +1 -1
  32. package/dist/embed/types.d.ts +2 -6
  33. package/dist/embed/types.d.ts.map +1 -1
  34. package/dist/ghost-core/catalog/assemble.d.ts.map +1 -1
  35. package/dist/ghost-core/catalog/assemble.js +1 -5
  36. package/dist/ghost-core/catalog/assemble.js.map +1 -1
  37. package/dist/ghost-core/catalog/closest.d.ts +1 -1
  38. package/dist/ghost-core/catalog/closest.js +1 -1
  39. package/dist/ghost-core/catalog/menu.d.ts +7 -9
  40. package/dist/ghost-core/catalog/menu.d.ts.map +1 -1
  41. package/dist/ghost-core/catalog/menu.js +4 -6
  42. package/dist/ghost-core/catalog/menu.js.map +1 -1
  43. package/dist/ghost-core/catalog/types.d.ts +2 -6
  44. package/dist/ghost-core/catalog/types.d.ts.map +1 -1
  45. package/dist/ghost-core/node/schema.d.ts +4 -4
  46. package/dist/ghost-core/node/schema.d.ts.map +1 -1
  47. package/dist/ghost-core/node/schema.js +10 -4
  48. package/dist/ghost-core/node/schema.js.map +1 -1
  49. package/dist/ghost-core/node/serialize.d.ts +5 -7
  50. package/dist/ghost-core/node/serialize.d.ts.map +1 -1
  51. package/dist/ghost-core/node/serialize.js +9 -18
  52. package/dist/ghost-core/node/serialize.js.map +1 -1
  53. package/dist/ghost-core/node/types.d.ts +5 -7
  54. package/dist/ghost-core/node/types.d.ts.map +1 -1
  55. package/dist/init-payloads/median/median-tells.md +27 -26
  56. package/dist/init-payloads/{vessel-light/anti-goal.median.md → median/standard.model-defaults.md} +8 -4
  57. package/dist/init-payloads/skeleton/brand.md +8 -4
  58. package/dist/init-payloads/skeleton/context.conversation.md +23 -14
  59. package/dist/init-payloads/skeleton/foundation.color.md +37 -29
  60. package/dist/init-payloads/skeleton/foundation.composition.md +18 -16
  61. package/dist/init-payloads/skeleton/foundation.controls.md +21 -13
  62. package/dist/init-payloads/skeleton/foundation.layout.md +33 -29
  63. package/dist/init-payloads/skeleton/foundation.motion.md +23 -17
  64. package/dist/init-payloads/skeleton/foundation.type.md +36 -29
  65. package/dist/init-payloads/skeleton/foundation.voice.md +17 -12
  66. package/dist/init-payloads/skeleton/glossary.md +33 -21
  67. package/dist/init-payloads/vessel-light/checks/conversation-grammar.md +2 -2
  68. package/dist/init-payloads/vessel-light/checks/median-tells.md +25 -25
  69. package/dist/init-payloads/vessel-light/checks/motion-restraint.md +2 -2
  70. package/dist/init-payloads/vessel-light/checks/relationships.md +4 -4
  71. package/dist/init-payloads/vessel-light/checks/shape-matches-job.md +9 -9
  72. package/dist/init-payloads/vessel-light/checks/values.md +6 -6
  73. package/dist/init-payloads/vessel-light/context.conversation.md +53 -0
  74. package/dist/init-payloads/vessel-light/context.data-density.md +51 -0
  75. package/dist/init-payloads/vessel-light/context.editorial.md +53 -0
  76. package/dist/init-payloads/vessel-light/context.email.md +53 -0
  77. package/dist/init-payloads/vessel-light/foundation.color-roles.md +41 -0
  78. package/dist/init-payloads/vessel-light/foundation.deletion.md +53 -0
  79. package/dist/init-payloads/vessel-light/foundation.hierarchy.md +73 -0
  80. package/dist/init-payloads/vessel-light/foundation.job.md +65 -0
  81. package/dist/init-payloads/vessel-light/foundation.motion.md +46 -0
  82. package/dist/init-payloads/vessel-light/foundation.palette.md +57 -0
  83. package/dist/init-payloads/vessel-light/foundation.rhythm.md +39 -0
  84. package/dist/init-payloads/vessel-light/foundation.shape.md +39 -0
  85. package/dist/init-payloads/vessel-light/foundation.surfaces.md +45 -0
  86. package/dist/init-payloads/vessel-light/foundation.tells.md +39 -0
  87. package/dist/init-payloads/vessel-light/foundation.temperature.md +62 -0
  88. package/dist/init-payloads/vessel-light/{signature.type.md → foundation.type.md} +28 -13
  89. package/dist/init-payloads/vessel-light/glossary.md +27 -30
  90. package/dist/init-payloads/vessel-light/index.md +19 -16
  91. package/dist/init-payloads/{median/cliche.median.md → vessel-light/standard.model-defaults.md} +1 -1
  92. package/dist/observability-events.js +2 -2
  93. package/dist/review/baseline.d.ts +1 -1
  94. package/dist/review/baseline.d.ts.map +1 -1
  95. package/dist/review/baseline.js +2 -2
  96. package/dist/review/baseline.js.map +1 -1
  97. package/dist/review/review-packet.d.ts +2 -1
  98. package/dist/review/review-packet.d.ts.map +1 -1
  99. package/dist/review/review-packet.js +6 -4
  100. package/dist/review/review-packet.js.map +1 -1
  101. package/dist/scan/check-scaffold.d.ts.map +1 -1
  102. package/dist/scan/check-scaffold.js +25 -3
  103. package/dist/scan/check-scaffold.js.map +1 -1
  104. package/dist/scan/fingerprint-package-lint.d.ts.map +1 -1
  105. package/dist/scan/fingerprint-package-lint.js +9 -17
  106. package/dist/scan/fingerprint-package-lint.js.map +1 -1
  107. package/dist/scan/templates.js +4 -4
  108. package/dist/scan/templates.js.map +1 -1
  109. package/dist/skill-bundle/SKILL.md +28 -45
  110. package/dist/skill-bundle/references/authoring.md +7 -7
  111. package/dist/skill-bundle/references/ground.md +58 -0
  112. package/dist/skill-bundle/references/making.md +71 -103
  113. package/dist/skill-bundle/references/{concrete.md → materials.md} +2 -2
  114. package/dist/skill-bundle/references/nodes.md +39 -15
  115. package/dist/skill-bundle/references/schema.md +10 -6
  116. package/dist/skill-bundle/references/steering-audit.md +9 -15
  117. package/dist/untrusted-framing.d.ts +9 -0
  118. package/dist/untrusted-framing.d.ts.map +1 -0
  119. package/dist/untrusted-framing.js +15 -0
  120. package/dist/untrusted-framing.js.map +1 -0
  121. package/package.json +1 -1
  122. package/dist/commands/pulse-command.d.ts +0 -3
  123. package/dist/commands/pulse-command.d.ts.map +0 -1
  124. package/dist/commands/pulse-command.js.map +0 -1
  125. package/dist/init-payloads/vessel-light/anti-goal.tells.md +0 -38
  126. package/dist/init-payloads/vessel-light/grammar.color-roles.md +0 -28
  127. package/dist/init-payloads/vessel-light/grammar.conversation.md +0 -29
  128. package/dist/init-payloads/vessel-light/grammar.deletion.md +0 -35
  129. package/dist/init-payloads/vessel-light/grammar.hierarchy.md +0 -56
  130. package/dist/init-payloads/vessel-light/grammar.job.md +0 -54
  131. package/dist/init-payloads/vessel-light/grammar.motion.md +0 -25
  132. package/dist/init-payloads/vessel-light/grammar.rhythm.md +0 -25
  133. package/dist/init-payloads/vessel-light/grammar.surfaces.md +0 -33
  134. package/dist/init-payloads/vessel-light/register.data-density.md +0 -39
  135. package/dist/init-payloads/vessel-light/register.editorial.md +0 -41
  136. package/dist/init-payloads/vessel-light/register.email.md +0 -43
  137. package/dist/init-payloads/vessel-light/signature.palette.md +0 -45
  138. package/dist/init-payloads/vessel-light/signature.shape.md +0 -27
  139. package/dist/init-payloads/vessel-light/signature.temperature.md +0 -44
  140. package/dist/skill-bundle/references/brief.md +0 -50
  141. package/dist/skill-bundle/references/recall.md +0 -36
  142. package/dist/skill-bundle/references/self-check.md +0 -64
@@ -1,10 +1,14 @@
1
1
  ---
2
- context: Any greenfield visual surface or first-draft copy.
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
@@ -1,14 +1,13 @@
1
1
  ---
2
- context: Any task that should express this brand.
2
+ for: Any task that should express this brand.
3
3
  ---
4
4
 
5
5
  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.
@@ -1,24 +1,33 @@
1
1
  ---
2
- context: Chat threads, agent consoles, and prompt composers.
2
+ for: Chat threads, agent consoles, and prompt composers.
3
3
  ---
4
4
 
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.
@@ -1,39 +1,47 @@
1
1
  ---
2
- context: Choosing or applying color.
2
+ for: Choosing or applying color.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  Color is assigned by role, not by taste. The roles are the source of truth;
8
11
  raw color values are implementation detail, never product language. If a
9
- container needs a color, it first needs a role: `background`, `foreground`,
10
- `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `border`,
11
- `input`, `ring`, and the status roles.
12
-
13
- The status roles — destructive, success, warning, info — exist only when
14
- meaning demands them. Destructive means destructive or error. Success means
15
- success. None of them are brand accents.
16
-
17
- One view does not perform a color palette. If a status color is present, the
18
- rest of the view stays on the base roles. Richness beyond this comes from a
19
- 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
20
14
  allows — a marketing page may turn it up; a settings form stays quiet.
21
15
 
22
- ## Palette
23
-
24
- Open — ask the human; do not freehand. The fixed relationship: a quiet base
25
- spine is the default atmosphere in every medium, and a closed expression set
26
- supplies the rest, its volume set by situation, never by taste. The open
27
- question: what is this brand's base spine, and what are the named hues of
28
- its expression set how many, and which? When the human answers, restate
29
- this section as the brand's current answer and record the values where your
30
- materials live. Until then, proceed with a quiet provisional spine and label
31
- it provisional.
32
-
33
- ## Misuse
34
-
35
- - Status colors never moonlight as atmosphere, in any context.
36
- - Expression never touches what you click. Buttons, inputs, and links stay
37
- 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
38
45
  system.
39
- - 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.
@@ -1,30 +1,32 @@
1
1
  ---
2
- context: Assembling any view.
2
+ for: Assembling any view.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  Composition is the layer above layout: layout gives the stacks and gaps;
8
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.
9
14
 
10
- Every view has exactly one focal point — one element at the largest scale.
11
- If two elements compete for primacy, demote or delete one; never resolve
12
- the tie by making both big.
13
-
14
- One primary action per view: the action the view exists to complete.
15
- Everything else steps down the control ladder (see the controls
16
- foundation). If two buttons both look primary, the composition failed.
17
-
18
- Actions land last. Calls to action render at the end of reading order —
19
- the user reads, then decides.
15
+ ## Rules
20
16
 
21
- Separation escalates: whitespace first, then a divider, then a container
22
- in that order, never skipping a step.
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.
23
25
 
24
- ## Misuse
26
+ ## Never
25
27
 
26
- - Never fake a focal point with decoration. Primacy comes from scale,
28
+ - Never fake a focal point with decoration primacy comes from scale,
27
29
  position, and space.
28
30
  - Never promote a second action to primary because something wants
29
- emphasis; step the other one down instead.
31
+ emphasis step the other one down instead.
30
32
  - Never separate with a container when whitespace would do.
@@ -1,7 +1,10 @@
1
1
  ---
2
- context: Any view with actions or inputs.
2
+ for: Any view with actions or inputs.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  The control emphasis ladder is exactly five rungs: primary, secondary,
@@ -12,18 +15,23 @@ may hold is a composition rule — see the composition foundation: one.
12
15
  Destructive is a meaning, not a rung. It is rare, it names the destructive
13
16
  act directly, and it is never borrowed for urgency, emphasis, or brand heat.
14
17
 
15
- Fields are quiet until active: hairline border, muted placeholder, clear
16
- label, and a focus ring when the user engages. The ring is guidance, not
17
- decoration. Errors state facts next to the field that caused them — never
18
- hidden in modals, toasts, or generic banners when the user needs to fix one
19
- input.
18
+ Fields are quiet until active. The focus ring is guidance, not decoration.
19
+
20
+ ## Rules
20
21
 
21
- Controls take the control radius; see the layout foundation for the two
22
- radius roles.
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.
23
30
 
24
- ## Misuse
31
+ ## Never
25
32
 
26
- - Never two competing primary buttons.
27
- - Never destructive styling as attention-getting.
28
- - Never expression color on a control — what you click stays on the base
29
- roles everywhere.
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.
@@ -1,45 +1,49 @@
1
1
  ---
2
- context: Laying out any view.
2
+ for: Laying out any view.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  All layout is stacks. Rhythm comes from relationships between siblings, not
8
- from isolated margins pasted onto whichever element was last touched. The
9
- gap steps are exactly five: `--gap-xs` through `--gap-xl`. Choose the gap
10
- 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
11
13
  screenshot pass. The default is column, medium gap. Columns are for almost
12
14
  everything — forms, cards, modal bodies, settings, page sections. Rows are
13
15
  conditional: controls, metadata lines, paired label/value moments. If a row
14
16
  wraps awkwardly, it wanted to be a column.
15
17
 
16
18
  Surface is the only way an element gets a background, border, radius, or
17
- shadow. The vocabulary is closed: role, padding, radius, border, elevation.
18
- The default surface is flat no border, no shadow. We do not outline
19
- everything to prove layout exists.
20
-
21
- The elevation tiers are exactly three: card, popover, modal. Elevation
22
- implies hierarchy — a card sits in flow, a popover floats above it, a modal
23
- 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.
24
22
 
25
23
  Borders are structural — inputs and overlays — not decorative frames around
26
24
  ordinary text. Use space, tone, and type hierarchy instead.
27
25
 
28
- ## Radius
29
-
30
- Open ask the human; do not freehand. The fixed relationship: controls and
31
- surfaces carry different radius roles, and the two never swap. Buttons and
32
- inputs take `--radius-control`; cards and containers take
33
- `--radius-surface`. One radius for what you click, one for what contains.
34
- The open question: how round is a control, and how round is a surface? When
35
- answered, restate this section as the brand's current answer. Until then,
36
- choose provisional values and label them.
37
-
38
- ## Misuse
39
-
40
- - No ad-hoc margins between siblings they hide the rhythm. Change the
41
- stack gap or split the stack.
42
- - No custom shadows because a composition feels flat, and no modal gravity
43
- on a routine card. Component shadows belong to the primitives that own
44
- them.
45
- - 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.
@@ -1,34 +1,40 @@
1
1
  ---
2
- context: Any transition, animation, or hover treatment.
2
+ for: Any transition, animation, or hover treatment.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  Motion is evidence of a state change. It confirms hover, press, reveal,
8
11
  collapse, entrance, exit, and spatial movement. It does not entertain.
9
-
10
- The entire vocabulary is three duration roles and one ease. Fast is for
11
- hover and press. Normal is for reveals, fades, and small state changes. Slow
12
- is reserved for spatial transitions where the user needs to understand
13
- movement. Prefer opacity and small transforms.
12
+ Prefer opacity and small transforms.
14
13
 
15
14
  In editorial and marketing contexts, entrances may be staged — scroll
16
15
  reveals and section transitions are part of editorial rhythm, still built
17
16
  from the three durations and the one ease. In product UI the same staging is
18
17
  decoration.
19
18
 
20
- ## Character
19
+ ## Rules
21
20
 
22
- Open ask the human; do not freehand. Motion and voice share one
23
- temperature: however warm or cool the brand's words are, its movement
24
- matches. See the voice foundation for the other half of this answer. The
25
- open question here: what character does the one ease carry? When answered,
26
- restate this section. Until then, use a quiet standard ease and label it
27
- 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.
28
32
 
29
- ## Misuse
33
+ ## Never
30
34
 
31
- - Nothing loops except explicit loading states. Decorative pulsing,
35
+ - Never loop anything except explicit loading states decorative pulsing,
32
36
  floating, glowing, and attention-seeking keyframes are off-language.
33
- - No novelty easings because a surface feels static.
34
- - 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.
@@ -1,44 +1,51 @@
1
1
  ---
2
- context: Any view containing text.
2
+ for: Any view containing text.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  Hierarchy is a closed vocabulary, not a size slider. Every piece of text
8
11
  picks from a named set; anything outside the set is a broken primitive, not
9
- a variant.
10
-
11
- The text variants are exactly six: display, headline, title, body, label,
12
- mono. 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. Mono carries code and machine detail.
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.
16
16
 
17
- The tones are exactly seven: default, muted, inverse, success, warning,
18
- info, destructive. Tone is part of the message. Hierarchy starts with tone
19
- and weight before size a secondary note usually wants muted body or label,
20
- not a smaller custom font. If prose needs emphasis, improve the sentence
21
- 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.
22
21
 
23
22
  The heading scale is editorial: it exists for pages composed outside the
24
23
  text variants — heroes and editorial moments. Product UI never mixes the two
25
24
  vocabularies in one view. A modal title is not a poster.
26
25
 
27
- Balanced text is for headings and compact statements, never long body copy.
28
-
29
- ## Typeface
30
-
31
- Open — ask the human; do not freehand. The fixed relationship: one typeface
32
- is the voice of the interface, everywhere, with a mono partner only for
33
- code, tool detail, and machine output. The open question: what typeface is
34
- this brand's voice, what mono partners it, and what rhythm does the
35
- editorial heading scale carry? When answered, restate this section as the
36
- brand's current answer. Until then, choose a quiet provisional pair and
37
- label it provisional.
26
+ ## Rules
38
27
 
39
- ## Misuse
40
-
41
- - No faked hierarchy with arbitrary font sizes. Choose the variant that
42
- 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.
43
32
  - Status tones appear only when the words carry that state meaning.
44
- - 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.
@@ -1,7 +1,10 @@
1
1
  ---
2
- context: Writing or editing any copy.
2
+ for: Writing or editing any copy.
3
3
  ---
4
4
 
5
+ Starter guidance the brand owner has not yet reviewed. Cite it as provisional
6
+ until a human edits or confirms this chapter.
7
+
5
8
  ## Usage
6
9
 
7
10
  Copy states what happened, what is possible, or what the user must decide.
@@ -12,18 +15,20 @@ Voice and motion carry the same temperature: a brand whose copy is warm does
12
15
  not move coldly, and a brand whose copy is spare does not bounce. When you
13
16
  set one, check the other.
14
17
 
15
- ## Warmth
18
+ ## Rules
16
19
 
17
- Open ask the human; do not freehand. The open question: how warm or cool
18
- does this brand sound and, by the shared temperature, how does it move?
19
- See the motion foundation for the other half. When answered, restate this
20
- section as the brand's current answer. Until then, write plainly and label
21
- 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.
22
26
 
23
- ## Misuse
27
+ ## Never
24
28
 
25
- - No exclamation points as a substitute for having something to say.
26
- - 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
27
32
  step.
28
- - Never restate this section as answered when it was your own provisional
29
- 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.
@@ -1,39 +1,51 @@
1
1
  ---
2
2
  kinds:
3
+ - name: standard
3
4
  - name: foundation
4
5
  - name: context
5
- - name: cliche
6
6
  ---
7
7
 
8
+ # standard
9
+
10
+ Shared guidance that is not specific to this brand. Every rule carries one of
11
+ two authority labels. An **Obligation** is a requirement brand preference
12
+ cannot waive — accessibility, safety, honesty, functional integrity; the
13
+ brand controls how it is expressed, not whether it holds. A **Default** is a
14
+ recommended starting position that protects unsteered work from generic model
15
+ behavior; explicit brand guidance in the cover, a foundation, or a matching
16
+ context may deliberately replace it. When a default with a paired check is
17
+ overridden, adapt or remove the check flag in the same change.
18
+
8
19
  # foundation
9
20
 
10
- The core elements — color, type, controls, layout, motion, voice — plus
11
- composition, the rules for assembling them into a view. Each foundation
12
- node is a chapter: usage rules that hold no matter what the brand values
13
- turn out to be, the brand's open questions (unanswered in this starter,
14
- marked as decisions only a human can make), and the chapter's misuse list.
15
- Follow the usage rules as written. Never fill in an open value and present
16
- it as the brand's.
21
+ The brand's load-bearing decisions — color, type, controls, layout, motion,
22
+ voice, and composition, the rules for assembling them into a view. Each
23
+ foundation node is a chapter: usage law that holds no matter what the brand
24
+ values turn out to be, the brand's open questions (unanswered in this
25
+ starter, marked as decisions only a human can make), and the chapter's
26
+ rejected moves. Follow the rules as written. Never fill in an open value and
27
+ present it as the brand's. A brand carries only the foundations its evidence
28
+ supports; these chapters are subjects, not mandatory slots.
17
29
 
18
30
  # context
19
31
 
20
32
  Where the defaults bend: a context names a situation — an AI conversation
21
33
  thread, a data-dense console, a transactional email — and states only what
22
- inverts there. Read a context only when its situation matches the task.
23
- Rules from the wrong context are contamination, not guidance.
24
-
25
- # cliche
26
-
27
- The defaults a generative model falls back on when no brand is steering it.
28
- These are nobody's brand. Each entry pairs the tired move with the honest
29
- replacement. Gather before styling anything greenfield; enforced by paired
30
- checks at review.
34
+ inverts there. A situation may combine surface, channel, modality, audience,
35
+ or moment. Read a context only when its situation matches the task. Rules
36
+ from the wrong context are contamination, not guidance.
31
37
 
32
38
  ---
33
39
 
40
+ Node bodies in this package follow one shape: `## Usage` carries the
41
+ worldview and decision logic; `## Rules` carries observable requirements a
42
+ reviewer can assess in the finished artifact; `## Never` pairs each rejected
43
+ move with its replacement; an optional `## Skeleton` (always last) carries
44
+ literal opening structure. A node includes only the sections it needs.
45
+
34
46
  The cover node (`brand.md`, declared in the manifest) is the one page always
35
47
  in context: what the brand is, its temperature, and the refusals only it
36
- makes. The ghost skill's `authoring` recipe explains how to grow this skeleton
37
- into a real ghost package: write the cover, answer each
38
- chapter's open question, prune the cliches your chapters absorb, then add
39
- materials and examples.
48
+ makes. The ghost skill's `authoring` recipe explains how to grow this starter
49
+ into a real ghost package: write the cover, answer each chapter's open
50
+ question, prune the shared defaults your chapters absorb, then add materials
51
+ and examples.
@@ -3,8 +3,8 @@ name: Conversation grammar
3
3
  description: Flags conversation UI that breaks plain assistant text, prompt-input structure, primary-action discipline, or collapsed tool output.
4
4
  severity: high
5
5
  references:
6
- - grammar.conversation
7
- - grammar.surfaces
6
+ - context.conversation
7
+ - foundation.surfaces
8
8
  ---
9
9
 
10
10
  Apply this check to diffs that touch AI threads, agent consoles, prompt composers, chat messages, or tool-call rendering.