@design-intelligence/ghost 0.30.0 → 0.31.1

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 (61) hide show
  1. package/README.md +1 -0
  2. package/dist/init-payloads/median/median-tells.md +27 -26
  3. package/dist/init-payloads/{vessel-light/anti-goal.median.md → median/standard.model-defaults.md} +7 -3
  4. package/dist/init-payloads/skeleton/brand.md +7 -3
  5. package/dist/init-payloads/skeleton/context.conversation.md +22 -13
  6. package/dist/init-payloads/skeleton/foundation.color.md +33 -28
  7. package/dist/init-payloads/skeleton/foundation.composition.md +14 -15
  8. package/dist/init-payloads/skeleton/foundation.controls.md +20 -15
  9. package/dist/init-payloads/skeleton/foundation.layout.md +29 -28
  10. package/dist/init-payloads/skeleton/foundation.motion.md +19 -16
  11. package/dist/init-payloads/skeleton/foundation.type.md +32 -28
  12. package/dist/init-payloads/skeleton/foundation.voice.md +13 -11
  13. package/dist/init-payloads/skeleton/glossary.md +33 -21
  14. package/dist/init-payloads/vessel-light/checks/conversation-grammar.md +2 -2
  15. package/dist/init-payloads/vessel-light/checks/median-tells.md +25 -25
  16. package/dist/init-payloads/vessel-light/checks/motion-restraint.md +2 -2
  17. package/dist/init-payloads/vessel-light/checks/relationships.md +4 -4
  18. package/dist/init-payloads/vessel-light/checks/shape-matches-job.md +9 -9
  19. package/dist/init-payloads/vessel-light/checks/values.md +6 -6
  20. package/dist/init-payloads/vessel-light/context.conversation.md +53 -0
  21. package/dist/init-payloads/vessel-light/context.data-density.md +51 -0
  22. package/dist/init-payloads/vessel-light/context.editorial.md +53 -0
  23. package/dist/init-payloads/vessel-light/context.email.md +53 -0
  24. package/dist/init-payloads/vessel-light/foundation.color-roles.md +41 -0
  25. package/dist/init-payloads/vessel-light/foundation.deletion.md +53 -0
  26. package/dist/init-payloads/vessel-light/foundation.hierarchy.md +73 -0
  27. package/dist/init-payloads/vessel-light/{grammar.job.md → foundation.job.md} +39 -28
  28. package/dist/init-payloads/vessel-light/foundation.motion.md +46 -0
  29. package/dist/init-payloads/vessel-light/foundation.palette.md +57 -0
  30. package/dist/init-payloads/vessel-light/foundation.rhythm.md +39 -0
  31. package/dist/init-payloads/vessel-light/foundation.shape.md +39 -0
  32. package/dist/init-payloads/vessel-light/foundation.surfaces.md +45 -0
  33. package/dist/init-payloads/vessel-light/foundation.tells.md +39 -0
  34. package/dist/init-payloads/vessel-light/{signature.temperature.md → foundation.temperature.md} +31 -13
  35. package/dist/init-payloads/vessel-light/{signature.type.md → foundation.type.md} +27 -12
  36. package/dist/init-payloads/vessel-light/glossary.md +27 -30
  37. package/dist/init-payloads/vessel-light/index.md +18 -15
  38. package/dist/scan/check-scaffold.d.ts.map +1 -1
  39. package/dist/scan/check-scaffold.js +25 -3
  40. package/dist/scan/check-scaffold.js.map +1 -1
  41. package/dist/scan/templates.js +4 -4
  42. package/dist/scan/templates.js.map +1 -1
  43. package/dist/skill-bundle/references/ground.md +3 -2
  44. package/dist/skill-bundle/references/nodes.md +29 -6
  45. package/dist/skill-bundle/references/schema.md +5 -0
  46. package/dist/skill-bundle/references/steering-audit.md +2 -2
  47. package/package.json +1 -1
  48. package/dist/init-payloads/vessel-light/anti-goal.tells.md +0 -38
  49. package/dist/init-payloads/vessel-light/grammar.color-roles.md +0 -28
  50. package/dist/init-payloads/vessel-light/grammar.conversation.md +0 -29
  51. package/dist/init-payloads/vessel-light/grammar.deletion.md +0 -35
  52. package/dist/init-payloads/vessel-light/grammar.hierarchy.md +0 -56
  53. package/dist/init-payloads/vessel-light/grammar.motion.md +0 -25
  54. package/dist/init-payloads/vessel-light/grammar.rhythm.md +0 -25
  55. package/dist/init-payloads/vessel-light/grammar.surfaces.md +0 -33
  56. package/dist/init-payloads/vessel-light/register.data-density.md +0 -39
  57. package/dist/init-payloads/vessel-light/register.editorial.md +0 -41
  58. package/dist/init-payloads/vessel-light/register.email.md +0 -43
  59. package/dist/init-payloads/vessel-light/signature.palette.md +0 -45
  60. package/dist/init-payloads/vessel-light/signature.shape.md +0 -27
  61. /package/dist/init-payloads/{median/cliche.median.md → vessel-light/standard.model-defaults.md} +0 -0
@@ -0,0 +1,73 @@
1
+ ---
2
+ for: Any view containing text or actions.
3
+ materials:
4
+ - materials/primitives.css
5
+ - materials/examples/composition.form.html
6
+ ---
7
+
8
+ ## Usage
9
+
10
+ Hierarchy is a closed vocabulary, not a size slider. Every piece of text and
11
+ every control picks from a named set; anything outside the set is a broken
12
+ primitive, not a variant.
13
+
14
+ Variant names are jobs, not decoration. Display leads a rare editorial
15
+ moment. Headline names a section. Title anchors a card, dialog, or compact
16
+ region. Body carries reading. Label names structure — category tags, field
17
+ labels, bylines, metadata, compact status. Mono carries code and machine
18
+ detail.
19
+
20
+ Tone is part of the message. Default is the main reading plane. Muted carries
21
+ secondary information. Inverse is for dark or primary surfaces. Hierarchy
22
+ starts with tone and weight before size — a secondary note usually wants
23
+ muted body or label, not a smaller custom font. If the prose needs emphasis,
24
+ improve the sentence before adding a style.
25
+
26
+ Primary is for the action the screen exists to complete — if two buttons
27
+ both look primary, the hierarchy failed. And some views honestly earn none: a
28
+ steady status view or an open comparison has no action the screen exists to
29
+ complete, and promoting one anyway puts the system's thumb on the scale.
30
+ Zero is a valid spend.
31
+
32
+ Destructive is a meaning, not a rung: it is rare, and it names the
33
+ destructive act directly.
34
+
35
+ The focus ring is guidance, not decoration. Proportional figures in a data
36
+ column wobble, and a wobbling column reads as sloppy arithmetic. Mono already
37
+ carries tabular alignment for machine detail; the rule extends to any numeric
38
+ data in product UI.
39
+
40
+ The form reference shows the intended decision order: stacked labels and
41
+ fields, compact helper text, one submit, secondary escape. Copy the decision
42
+ order before adjusting surface detail.
43
+
44
+ ## Rules
45
+
46
+ - The text variants are exactly six: display, headline, title, body, label,
47
+ mono.
48
+ - The tones are exactly seven: default, muted, inverse, success, warning,
49
+ info, destructive.
50
+ - The four status tones appear only when the words have that state meaning.
51
+ - The control emphasis ladder is exactly five rungs: primary, secondary,
52
+ outline, ghost, link.
53
+ - At most one primary action per view (`--primary-budget: 1`); everything
54
+ else steps down the ladder.
55
+ - Fields are quiet until they are active: hairline border, muted
56
+ placeholder, clear label, and a focused ring when the user engages.
57
+ - Errors state facts next to the field that caused them.
58
+ - Figures that will be compared or scanned — amounts, counts, dates in
59
+ columns, any metric — set in tabular numerals (`--numeric-tabular`), with
60
+ the unit tight to the number.
61
+ - Balanced text is for headings and compact statements.
62
+
63
+ ## Never
64
+
65
+ - Never fake hierarchy with arbitrary font sizes — instead choose the tier
66
+ that matches the job, then use tone, weight, and spacing for the rest.
67
+ - Never borrow destructive for urgency, emphasis, or brand heat — instead
68
+ reserve it for the destructive act it names.
69
+ - Never hide field errors in modals, toasts, or generic banners when the
70
+ user needs to fix one input — instead state the facts next to the field
71
+ that caused them.
72
+ - Never balance long body copy into jagged reading — instead reserve
73
+ balanced text for headings and compact statements.
@@ -9,6 +9,8 @@ materials:
9
9
  - materials/examples/email.html
10
10
  ---
11
11
 
12
+ ## Usage
13
+
12
14
  Before any structure exists, name what the reader does next with the view.
13
15
  The topic never picks the shape; the reader's job does. A billing question
14
16
  is not "a billing page" — it is a form to fill, a table to scan, a decision
@@ -16,39 +18,48 @@ to confirm, or a thread to continue, and each of those is a different
16
18
  composition. A view built for the wrong job does not merely look off; it
17
19
  misleads.
18
20
 
19
- The jobs and where they route:
20
-
21
- - **Fill something in** — settings, signup, any submit-and-done task → the
22
- form example. Stacked labels and fields, one submit, secondary escape.
23
- - **Scan and compare records** — lists, audits, anything with rows and
24
- figures → the table example, in the data-density register.
25
- - **Read a narrative** — a landing page, an announcement, a story → the
26
- editorial example, in the editorial register.
27
- - **Stop and decide** — a confirmation, a destructive act, a choice that
28
- interrupts the task → the overlay example. The decision is the view.
29
- - **Converse with the system** — an AI thread, an agent console, a prompt
30
- composer → the conversation example.
31
- - **Be notified elsewhere** — receipts, alerts, anything that lands in an
32
- inbox → the email example, in the email register.
33
-
34
21
  Read the request's verbs, not its nouns: "edit / set up / submit" routes to
35
22
  form; "compare / list / review the records" to table; "announce / tell the
36
23
  story" to editorial; "confirm / are you sure" to overlay; "ask / draft with
37
24
  me" to conversation. When two jobs fold into one request, build for the job
38
25
  the reader performs on this view, now — the other job is the next view. When
39
- a job fits none of these, compose from the grammar and say so; do not force
40
- the nearest example.
26
+ a job fits none of these, compose from the grammar and say so.
41
27
 
42
- Three shapes lie about the job, and we refuse them everywhere:
28
+ Three shapes lie about the job, and we refuse them everywhere; they are
29
+ listed under Never.
43
30
 
44
- - A view whose content is an artifact the reader will review — a draft, a
45
- filled form, a generated plan — leads with the artifact, never with an
46
- announcement headline. "Here's your draft" in display type demotes the
47
- actual deliverable; the artifact sitting there with its actions is the
48
- statement that it is ready.
31
+ ## Rules
32
+
33
+ - **Fill something in** settings, signup, any submit-and-done task —
34
+ routes to the form example: stacked labels and fields, one submit,
35
+ secondary escape.
36
+ - **Scan and compare records** — lists, audits, anything with rows and
37
+ figures — routes to the table example, in the data-density context.
38
+ - **Read a narrative** — a landing page, an announcement, a story — routes
39
+ to the editorial example, in the editorial context.
40
+ - **Stop and decide** — a confirmation, a destructive act, a choice that
41
+ interrupts the task — routes to the overlay example. The decision is the
42
+ view.
43
+ - **Converse with the system** — an AI thread, an agent console, a prompt
44
+ composer — routes to the conversation example.
45
+ - **Be notified elsewhere** — receipts, alerts, anything that lands in an
46
+ inbox — routes to the email example, in the email context.
49
47
  - A view reporting a live or ongoing state carries its freshness — "updated
50
- 2 min ago" — in quiet metadata. Presenting a moving value as a settled
51
- fact is a small lie the reader eventually catches.
52
- - A view where the decision belongs to the reader presents the material and
53
- withholds the verdict. Recommendation framing on a choice the system
54
- cannot honestly make is manufactured confidence, and it reads that way.
48
+ 2 min ago" — in quiet metadata.
49
+
50
+ ## Never
51
+
52
+ - Never force the nearest example when a job fits none of these — instead
53
+ compose from the grammar and say so.
54
+ - Never lead with an announcement headline when the view's content is an
55
+ artifact the reader will review — a draft, a filled form, a generated
56
+ plan. "Here's your draft" in display type demotes the actual deliverable —
57
+ instead lead with the artifact; the artifact sitting there with its
58
+ actions is the statement that it is ready.
59
+ - Never present a moving value as a settled fact — it is a small lie the
60
+ reader eventually catches; instead carry the view's freshness — "updated
61
+ 2 min ago" — in quiet metadata.
62
+ - Never put recommendation framing on a choice the system cannot honestly
63
+ make — it is manufactured confidence, and it reads that way; instead
64
+ present the material and withhold the verdict when the decision belongs to
65
+ the reader.
@@ -0,0 +1,46 @@
1
+ ---
2
+ for: Any transition, animation, or hover treatment.
3
+ materials:
4
+ - materials/tokens.css
5
+ ---
6
+
7
+ ## Usage
8
+
9
+ Motion is evidence of a state change. It confirms hover, press, reveal,
10
+ collapse, entrance, exit, and spatial movement. It does not entertain.
11
+
12
+ The entire vocabulary is three duration roles and one ease. The ease's
13
+ character is a brand answer — see the temperature signature.
14
+
15
+ Prefer opacity and small transform changes. If removing an animation does not
16
+ reduce comprehension, the animation was decoration.
17
+
18
+ Condition: marketing and editorial surfaces may stage entrances — scroll
19
+ reveals and section transitions are part of editorial rhythm, still built
20
+ from the three durations and the one ease. In product UI the same staging is
21
+ decoration.
22
+
23
+ ## Rules
24
+
25
+ - The vocabulary is exactly three duration roles and one ease.
26
+ - Fast is for hover and press.
27
+ - Normal is for reveals, fades, and small state changes.
28
+ - Slow is reserved for spatial transitions where the user needs to
29
+ understand movement.
30
+ - Nothing loops except explicit loading states. A spinner may continue
31
+ because work continues.
32
+
33
+ ## Never
34
+
35
+ - Never introduce novelty easings because a surface feels static — instead
36
+ stay on the one ease; its character is a brand answer (see the temperature
37
+ signature).
38
+ - Never ship decorative pulsing, floating, glowing, or attention-seeking
39
+ keyframes — they are off-language; instead loop nothing except explicit
40
+ loading states.
41
+ - Never keep an animation whose removal does not reduce comprehension — it
42
+ was decoration; instead delete it and prefer opacity and small transform
43
+ changes where motion earns its place.
44
+ - Never stage entrances in product UI — that staging is decoration there;
45
+ instead reserve scroll reveals and section transitions for marketing and
46
+ editorial surfaces.
@@ -0,0 +1,57 @@
1
+ ---
2
+ for: Color beyond the base roles, in any register.
3
+ materials:
4
+ - materials/tokens.css
5
+ ---
6
+
7
+ ## Usage
8
+
9
+ This is Vessel's answer to palette — it stands until you replace it.
10
+
11
+ The relationship is fixed: one brand at different volumes. A monochrome spine
12
+ is the default atmosphere in every medium — calm, legible, and resistant to
13
+ novelty — and a closed expression set supplies the atmosphere, with volume
14
+ set by context, never by taste.
15
+
16
+ Expressive color outside the closed set is not expression; it is another
17
+ brand. An invented hue is not a bolder Vessel; it is a different brand.
18
+
19
+ Loudness comes from commitment to few colors at scale, not variety.
20
+
21
+ To adapt: edit the `--expression-*` values (and the gray ramp, if the spine
22
+ changes) in `materials/tokens.css` and restate this node's current answer.
23
+ The ladder — a quiet spine, a closed hue set, context-gated volume — is the
24
+ part worth keeping.
25
+
26
+ ## Rules
27
+
28
+ - The base palette is monochrome gray.
29
+ - The expression palette is five named hues and only these — amber
30
+ (`--expression-1`), periwinkle (`--expression-2`), clay
31
+ (`--expression-3`), orchid (`--expression-4`), sage (`--expression-5`).
32
+ - Product UI: expression lives only in data visualization. A chart may use
33
+ the hues; the interface around it stays monochrome.
34
+ - Data-dense consoles: one hue family may mark status. Nothing atmospheric.
35
+ Charts inside a console keep the product carve-out — hues stay inside the
36
+ plot area and never leak into rows, badges, or headers.
37
+ - Email: exactly one expressive moment per message — a header band or the
38
+ figure that matters. One hue, quiet everywhere else.
39
+ - Editorial: expression is sanctioned atmosphere — a tinted dark section, a
40
+ colored pull-quote accent, a duotone moment. Never more than two hues per
41
+ page.
42
+ - Two constants that outrank the ladder: expression never touches what you
43
+ click — buttons, inputs, and links stay monochrome in every context — and
44
+ the status roles are not expression; they keep their meanings everywhere.
45
+
46
+ ## Never
47
+
48
+ - Never use expressive color outside the five named hues — an invented hue
49
+ is not a bolder Vessel; it is a different brand; instead stay inside the
50
+ `--expression-*` set at the context's sanctioned volume.
51
+ - Never put expression on what you click — instead keep buttons, inputs, and
52
+ links monochrome in every context.
53
+ - Never let the status roles moonlight as atmosphere — they are not
54
+ expression; instead keep their meanings everywhere and draw atmosphere
55
+ from the expression set.
56
+ - Never set expression volume by taste — instead set it by context, per the
57
+ ladder above.
@@ -0,0 +1,39 @@
1
+ ---
2
+ for: Laying out any view.
3
+ materials:
4
+ - materials/primitives.css
5
+ ---
6
+
7
+ ## Usage
8
+
9
+ All layout is stacks. Rhythm comes from relationships between siblings, not
10
+ from isolated margins pasted onto whichever element was last touched.
11
+
12
+ Choose the gap that states the relationship. Ad-hoc margins between siblings
13
+ are forbidden because they hide the rhythm. When spacing feels wrong, change
14
+ the stack gap or split the stack.
15
+
16
+ Columns are for almost everything: forms, cards, message lists, modal bodies,
17
+ settings, empty states, and page sections. A column lets the user scan.
18
+
19
+ Rows are conditional. Use them for controls, metadata lines, compact status,
20
+ and paired label/value moments. If a row starts wrapping awkwardly, it
21
+ probably wanted to be a column.
22
+
23
+ ## Rules
24
+
25
+ - The gap steps are exactly five: `--gap-xs`, `--gap-sm`, `--gap-md`,
26
+ `--gap-lg`, `--gap-xl`.
27
+ - The default is column, medium gap, stretch alignment, start justification.
28
+ That is the ordinary reading rhythm.
29
+ - Rows are for controls, metadata lines, compact status, and paired
30
+ label/value moments.
31
+
32
+ ## Never
33
+
34
+ - Never place ad-hoc margins between siblings — they hide the rhythm;
35
+ instead change the stack gap or split the stack.
36
+ - Never tune by single pixels to make a screenshot pass — instead choose the
37
+ gap step that states the relationship.
38
+ - Never keep a row that starts wrapping awkwardly — it probably wanted to be
39
+ a column; instead convert it.
@@ -0,0 +1,39 @@
1
+ ---
2
+ for: Choosing or implementing any radius or corner treatment.
3
+ materials:
4
+ - materials/tokens.css
5
+ - materials/primitives.css
6
+ ---
7
+
8
+ ## Usage
9
+
10
+ This is Vessel's answer to shape — it stands until you replace it.
11
+
12
+ The relationship is fixed: controls and surfaces carry different radius
13
+ roles, and the two never swap. The pill is Vessel's most visible control
14
+ signature; a rectangular button is not a variant, it is a different design
15
+ system.
16
+
17
+ 20px is a considered position: rounder than default shadcn, but not bubbly.
18
+ Use the radius system as restraint, not as decoration.
19
+
20
+ To adapt: edit the `--radius-control` and `--radius-surface` values in
21
+ `materials/tokens.css` and restate this node's current answer. The
22
+ role split — one radius for what you click, one for what contains — is the
23
+ part worth keeping.
24
+
25
+ ## Rules
26
+
27
+ - Buttons and text inputs use `--radius-control`; cards and other surfaces
28
+ use `--radius-surface`.
29
+ - Controls are pills (`--radius-control: 999px`).
30
+ - Surfaces take the 20px signature radius (`--radius-surface: 20px`).
31
+
32
+ ## Never
33
+
34
+ - Never give a button the surface radius — a rectangular button is the
35
+ fastest tell that the output is not Vessel; instead controls take
36
+ `--radius-control`, the pill.
37
+ - Never swap the two radius roles — instead keep `--radius-control` on what
38
+ you click and `--radius-surface` on what contains.
39
+ - Never use the radius system as decoration — instead use it as restraint.
@@ -0,0 +1,45 @@
1
+ ---
2
+ for: Any card, popover, modal, dialog, scrim, or bordered container.
3
+ materials:
4
+ - materials/primitives.css
5
+ - materials/examples/composition.overlay.html
6
+ ---
7
+
8
+ ## Usage
9
+
10
+ Surface is the only way an element gets a background, border, radius, or
11
+ shadow. If a container needs visual treatment, it first needs a surface role.
12
+
13
+ The vocabulary is closed: role, padding, radius, border, and elevation. These
14
+ axes create enough range for page flow, cards, popovers, muted blocks,
15
+ accents, and dark moments without inventing one-off boxes.
16
+
17
+ Elevation implies hierarchy — a card sits in the document flow, a popover
18
+ floats above the flow, a modal interrupts the task. Pick the tier that
19
+ matches the interaction.
20
+
21
+ Borders are structural, especially for inputs and overlays. They are not
22
+ decorative frames around ordinary text.
23
+
24
+ The overlay reference shows the interrupting end of the system: background
25
+ scrim, modal radius, modal shadow, compact header, clear footer. Copy its
26
+ hierarchy when a user must stop and decide.
27
+
28
+ ## Rules
29
+
30
+ - The default surface is flat: no border, no shadow. We do not outline
31
+ everything to prove layout exists.
32
+ - The elevation tiers are exactly three: card, popover, modal.
33
+ - Component shadows belong to the primitives that own them.
34
+ - Borders are structural, especially for inputs and overlays.
35
+
36
+ ## Never
37
+
38
+ - Never write a custom shadow because the composition feels flat — instead
39
+ pick the elevation tier that matches the interaction.
40
+ - Never pair a low tier with an interrupting role or give a routine card
41
+ modal gravity — instead match the tier to the interaction's hierarchy.
42
+ - Never borrow component shadows for layout — they belong to the primitives
43
+ that own them; instead take layout elevation from the three tiers.
44
+ - Never use borders as decoration, especially around assistant text —
45
+ instead use space, tone, and type hierarchy.
@@ -0,0 +1,39 @@
1
+ ---
2
+ for: Any work applying this brand's signature.
3
+ ---
4
+
5
+ ## Usage
6
+
7
+ These are the near-misses of Vessel's own signature: outputs that got close
8
+ enough to cite the brand and still missed it. Each reject names its
9
+ replacement. When a tell fires, the fix direction is always toward the
10
+ token, the role, or deletion — never toward adding a compensating style on
11
+ top of the miss.
12
+
13
+ Fidelity note: pills and fluid clamp display headings are medians Vessel
14
+ deliberately shares — their presence is fidelity, not drift. Convergence is
15
+ not the crime; surrendering the choice is.
16
+
17
+ ## Never
18
+
19
+ - Never ship rectangular buttons. A rectangular button is not a variant; it
20
+ is a different design system — instead controls take `--radius-control`,
21
+ the pill.
22
+ - Never swap radius roles: the surface radius on a control, the pill on a
23
+ surface, or 20px cells in a data table — instead `--radius-control` on
24
+ what you click, `--radius-surface` on what contains, small radius on data
25
+ cells.
26
+ - Never put expression hues on interactive controls, invent a sixth hue, or
27
+ pass off a tinted gray as monochrome — instead use the five named
28
+ expression hues at the context's sanctioned volume, and a true gray spine.
29
+ An invented hue is not a bolder Vessel; it is a different brand.
30
+ - Never write custom shadows that sit near a tier — instead use the exact
31
+ tier — card, popover, or modal — chosen by interaction importance.
32
+ - Never borrow `--shadow-btn` for layout — component shadows belong to the
33
+ primitives that own them; instead take layout elevation from the three
34
+ tiers.
35
+ - Never use editorial display type in product UI, or product type timidity
36
+ in editorial — instead each context keeps its own vocabulary; a modal
37
+ title is not a poster, and a hero at product scale reads as timid.
38
+ - Never put borders around assistant text — instead the assistant speaks as
39
+ plain text on the page surface; use space, tone, and type hierarchy.
@@ -4,19 +4,15 @@ materials:
4
4
  - materials/tokens.css
5
5
  ---
6
6
 
7
+ ## Usage
8
+
7
9
  This is Vessel's answer to temperature — it stands until you replace it.
8
10
 
9
11
  The relationship is fixed: voice and motion carry the same temperature. Copy
10
12
  states what happened, what is possible, or what the user must decide — it
11
13
  does not perform personality — and motion confirms rather than entertains.
12
14
 
13
- Vessel's current answer in words: product UI is the default register —
14
- factual, quiet, sentence case, and free of applause. No exclamation marks;
15
- celebration is not reassurance. Confirmations are quiet: "Changes saved",
16
- never "Awesome!" The system should sound reliable, not excited by basic
17
- competence. Errors name the problem and the fix in the place where the user
18
- can act; a vague failure banner is evasion. Buttons name the act — "Delete
19
- account", "Save changes", "Invite member", not "Do it" or "Let's go".
15
+ The system should sound reliable, not excited by basic competence.
20
16
  Destructive copy is direct because the risk is direct; softening the verb
21
17
  makes the interface less honest. Vessel never celebrates at the user. Trust
22
18
  comes from precision, restraint, and naming the truth plainly.
@@ -28,12 +24,7 @@ card expired". "You might want to consider updating your billing info" →
28
24
  "Update your billing info". Strip the apology, the applause, and the hedge;
29
25
  keep the fact and the fix.
30
26
 
31
- Vessel's current answer in motion: three durations — `--duration-fast`,
32
- `--duration-normal`, `--duration-slow` — and one ease, `--ease-spring`, which
33
- should feel resolved without feeling elastic. Hover confirms with color and
34
- background shifts at the fast duration, not levitation.
35
-
36
- Condition: editorial surfaces switch register. Short declarative confident
27
+ Condition: editorial surfaces switch context. Short declarative confident
37
28
  fragments are correct in heroes and section headings. That same editorial
38
29
  confidence is wrong in a settings form — product copy serves the task before
39
30
  it serves the voice. Email copy uses the product voice: factual, not
@@ -42,3 +33,30 @@ campaign-like.
42
33
  To adapt: rewrite this node's current answers in your brand's voice and edit
43
34
  the duration and ease values in `materials/tokens.css`. The coupling — words
44
35
  and motion sharing one temperature — is the part worth keeping.
36
+
37
+ ## Rules
38
+
39
+ - Product UI is the default context — factual, quiet, sentence case, and
40
+ free of applause.
41
+ - No exclamation marks; celebration is not reassurance.
42
+ - Confirmations are quiet: "Changes saved", never "Awesome!"
43
+ - Errors name the problem and the fix in the place where the user can act.
44
+ - Buttons name the act — "Delete account", "Save changes", "Invite member",
45
+ not "Do it" or "Let's go".
46
+ - Motion carries three durations — `--duration-fast`, `--duration-normal`,
47
+ `--duration-slow` — and one ease, `--ease-spring`, which should feel
48
+ resolved without feeling elastic.
49
+ - Hover confirms with color and background shifts at the fast duration.
50
+
51
+ ## Never
52
+
53
+ - Never ship a vague failure banner — it is evasion; instead name the
54
+ problem and the fix in the place where the user can act.
55
+ - Never soften the verb on destructive copy — it makes the interface less
56
+ honest; instead name the destructive act directly.
57
+ - Never celebrate at the user — instead let trust come from precision,
58
+ restraint, and naming the truth plainly.
59
+ - Never confirm hover with levitation — instead confirm with color and
60
+ background shifts at the fast duration.
61
+ - Never carry editorial confidence into a settings form — instead let
62
+ product copy serve the task before it serves the voice.
@@ -11,6 +11,8 @@ materials:
11
11
  - materials/fonts/HKGrotesk-SemiBold.woff2
12
12
  ---
13
13
 
14
+ ## Usage
15
+
14
16
  This is Vessel's answer to type — it stands until you replace it.
15
17
 
16
18
  The relationship is fixed: one typeface is the voice of the interface,
@@ -19,19 +21,9 @@ output. The heading scale is editorial — its tokens exist for pages composed
19
21
  outside the text variants — and product UI never mixes the two vocabularies
20
22
  in one view.
21
23
 
22
- Vessel's current answer: HK Grotesk. vessel-light ships it as its embedded
23
- voice — here, `tokens.css` is canonical.
24
-
25
- The heading scale is editorial: display, section, and sub each carry their
26
- own rhythm (`--heading-display-*`, `--heading-section-*`, `--heading-sub-*`).
27
24
  Display sizes use tight tracking and sub-1 line heights because the words
28
- behave like composition, not paragraph text. Card-level headings inside
29
- editorial features use the product `title` variant — the scale does not reach
30
- below sub.
31
-
32
- Labels are small, semibold, and tracked wide. They should feel precise, never
33
- loud. Body text keeps the established reading sizes with relaxed line height;
34
- do not shrink important prose until it becomes legal copy.
25
+ behave like composition, not paragraph text. Labels should feel precise,
26
+ never loud.
35
27
 
36
28
  Condition: display and section scale are for editorial or hero moments.
37
29
  Product UI lives in headline, title, body, label, and mono. A modal title is
@@ -41,3 +33,26 @@ To adapt: swap the font files, edit `--font-sans`, `--font-mono`, and the
41
33
  heading tokens in `materials/tokens.css`, and restate this node's current
42
34
  answer. The one-voice rule and the editorial/product vocabulary split are the
43
35
  parts worth keeping.
36
+
37
+ ## Rules
38
+
39
+ - The typeface is HK Grotesk. vessel-light ships it as its embedded voice —
40
+ here, `tokens.css` is canonical.
41
+ - The heading scale is editorial: display, section, and sub each carry their
42
+ own rhythm (`--heading-display-*`, `--heading-section-*`,
43
+ `--heading-sub-*`).
44
+ - Card-level headings inside editorial features use the product `title`
45
+ variant — the scale does not reach below sub.
46
+ - Labels are small, semibold, and tracked wide.
47
+ - Body text keeps the established reading sizes with relaxed line height.
48
+ - Product UI lives in headline, title, body, label, and mono.
49
+
50
+ ## Never
51
+
52
+ - Never mix the editorial heading scale and the product text variants in one
53
+ view — instead keep each vocabulary in its own context; a modal title is
54
+ not a poster.
55
+ - Never shrink important prose until it becomes legal copy — instead keep
56
+ body text at the established reading sizes with relaxed line height.
57
+ - Never make labels loud — instead keep them small, semibold, and tracked
58
+ wide so they feel precise.
@@ -1,44 +1,41 @@
1
1
  ---
2
2
  kinds:
3
- - name: grammar
4
- - name: signature
5
- - name: register
6
- - name: anti-goal
3
+ - name: standard
4
+ - name: foundation
5
+ - name: context
7
6
  ---
8
7
 
9
- # grammar
8
+ # standard
10
9
 
11
- The brand's decision logic: closed sets, role vocabularies, and assembly
12
- rules, stated in token roles and never in literal values. Grammar survives an
13
- adaptation unchanged adapt the package, swap every value, and these nodes still
14
- hold. Gather grammar before inventing structure.
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. A **Default** is a starting position that protects unsteered
13
+ work from generic model behavior; explicit brand guidance may deliberately
14
+ replace it. When a default with a paired check is overridden, adapt or remove
15
+ the check flag in the same change.
15
16
 
16
- # signature
17
+ # foundation
17
18
 
18
- The dials: the choices that make this brand this brand, each stated as a
19
- current answer that stands until you replace it. Signature nodes name real
20
- values because they are the values — on adaptation, edit the token roles in
21
- `materials/tokens.css` and restate the node. Gather signature before setting
22
- any value a dial governs.
19
+ Vessel's load-bearing decisions: the closed sets, role vocabularies, and
20
+ assembly rules, plus the answered identity dials shape, palette, type,
21
+ temperature each stating Vessel's current answer, which stands until you
22
+ replace it. The role logic survives an adaptation unchanged; the answered
23
+ values do not on adaptation, edit the token roles in `materials/tokens.css`
24
+ and restate each answer. Gather foundations before inventing structure or
25
+ setting any value a dial governs.
23
26
 
24
- # register
27
+ # context
25
28
 
26
- A condition-scoped contract: a situation — data-dense consoles, editorial
27
- pages, transactional email — where parts of the default rules invert. Each
28
- register names its condition first. Truths from the wrong register are
29
- poison, not context; gather a register only when its condition matches the
29
+ A named situation — data-dense consoles, editorial pages, transactional
30
+ email, conversation UI — where parts of the default rules bend or invert.
31
+ Each context names its condition first. Truths from the wrong context are
32
+ poison, not guidance; read a context only when its condition matches the
30
33
  task.
31
34
 
32
- # anti-goal
33
-
34
- What this package refuses, each reject paired with its replacement.
35
- `anti-goal.median` is the model's floor, not the brand's taste;
36
- `anti-goal.tells` is the near-miss map of this brand's own signature. Gather
37
- anti-goals before styling anything greenfield.
38
-
39
35
  ---
40
36
 
41
37
  To adapt this package to another brand, follow the starter section of the
42
- `authoring` recipe in the ghost skill bundle. In short: new manifest id, prune the
43
- median rules your brand legitimately violates, answer each signature node,
44
- edit `materials/tokens.css`, regenerate the examples, rewrite the tells.
38
+ `authoring` recipe in the ghost skill bundle. In short: new manifest id, prune
39
+ the shared model-defaults rules your brand legitimately violates, restate each
40
+ answered foundation dial, edit `materials/tokens.css`, regenerate the
41
+ examples, rewrite the tells.