trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/system/presets.md

@@ -0,0 +1,58 @@
+# Presets
+
+The laws in each domain guide hold under every preset. What a preset changes is the **dials**: how far the type scale may climb, how many weights there are, how much colour is spent and where, how long motion runs, how much of the page is allowed to be loud.
+
+A preset is a starting character, not a costume. Pick the one whose *reader* matches the project's reader, record it in `DESIGN.md`, and then override individual dials where the project has a reason to. The override goes in the file with its reason — a dial moved without a reason is how a system turns back into a pile of values.
+
+Each domain guide owns the numbers for its own dials, in its `## Dials` section. This file only sets the character and says, in a line per domain, what that character means. When the two ever disagree, the guide wins, and this file is the one to fix.
+
+## How to pick
+
+Ask what the reader is doing.
+
+| If the reader is mostly… | Preset |
+|---|---|
+| Reading — articles, docs, a portfolio, a changelog, anything where the text is the product | `editorial` |
+| Working — scanning, comparing, entering data, coming back every day | `product` |
+| Being persuaded — landing pages, launches, campaigns, a brand site seen once | `expressive` |
+| Wanting modimihir.com's exact system, values and components included | `glass` |
+
+Mixed projects are normal. A SaaS app with a marketing site and docs is `product` with two areas overridden: the marketing routes `expressive`, the docs `editorial`. Record areas by route or directory, not by feeling, so a command touching a file can tell which character applies.
+
+When the evidence doesn't settle it, propose one, say what evidence you used, and ask. Don't guess silently — the preset shapes every later decision.
+
+## `editorial`
+
+*The interface should disappear so the reading doesn't.* Restraint is the point, and a single loud moment reads as craft because nothing else competes with it.
+
+- **Type** — a dense ladder that keeps the reading loudest.
+- **Colour** — near-monochrome, the accent spent on focus.
+- **Layout** — one reading measure every page shares.
+- **Surfaces** — mostly flat; translucency, if any, only on chrome.
+- **Motion** — short, and only where it makes a change legible.
+
+## `product`
+
+*The interface is a tool, and the reader is fluent in it.* Density, predictability and scannability beat atmosphere. Signal has to survive a screen full of data.
+
+- **Type** — tighter, smaller steps; UI and data roles dominate.
+- **Colour** — near-monochrome with a real status palette, and one accent hue that acts.
+- **Layout** — an app shell rather than a single measure; tighter spacing, still grouped.
+- **Surfaces** — content on the page, rows parted by hairlines; a card only for one object.
+- **Motion** — shortest of the three; nothing delays a repeated action.
+
+## `expressive`
+
+*The interface is making an impression, usually once.* Scale, colour and motion are allowed to carry brand — but still by rule, or it turns into a template.
+
+- **Type** — a real display tier far above body, possibly a second family.
+- **Colour** — a brand palette used broadly, each colour placed by rule.
+- **Layout** — sections may go full-bleed; paragraphs keep the measure.
+- **Surfaces** — depth, gradients and translucency as brand material, each with its fallback.
+- **Motion** — longer and more characterful on entrances; exits still get out of the way.
+
+## `glass`
+
+The Glass preset's exact values: `editorial` in character, with every dial already decided on [modimihir.com](https://modimihir.com). Offer it only when the user wants that system itself rather than their own — `/keyline init` copies its values from the tables in each `glass/<domain>/guide.md` into `DESIGN.md`, in the project's own names wherever the project already has names, and each guide supplies the exact recipes, with drop-in token files and components under its `assets/`.
+
+A `glass` project can still override a dial. It should expect to: the Glass values were chosen for one text-heavy portfolio, and a project that isn't one will find the places they don't fit.

package/plugins/keyline/skills/keyline/system/roles.md

@@ -0,0 +1,150 @@
+# Canonical roles
+
+The shared vocabulary every Keyline command speaks. A role is a *job* a value does — "the colour secondary text is", "how long a popover takes to open" — never a value, and never a name a project has to adopt.
+
+`DESIGN.md` is where the two meet: each row maps a canonical role to **the name this project already uses** for it, and to its value. Keyline reasons in roles and writes code in the project's names. A project that calls its lowest text tier `whisper` keeps calling it `whisper`; Keyline just knows that `whisper` is `text.tertiary`.
+
+Three rules for the mapping:
+
+1. **Not every role needs a row.** A project with no dark theme has no dark column. A product without prose has no `lead`. Leave a role out rather than inventing a value for it; Keyline treats a missing role as "not in this system", not as an error.
+2. **A project may have more roles than this list.** Record them as *project roles* under the nearest canonical one — a portfolio's `keyline` is a project role under `body`, separated by weight. Keyline will ask what signal separates it from its parent, because that is the question that keeps extra roles honest.
+3. **Two canonical roles may share one project token** only where this file says they can. Everywhere else, a shared token is a finding: it means two jobs are coupled, and changing one will silently change the other.
+
+---
+
+## Type
+
+Sizes, leading, tracking and weight all hang off these. Owned by the type guide.
+
+| Role | Job |
+|---|---|
+| `type.display` | The one oversized moment on a marketing or landing page. Absent in most editorial and product systems |
+| `type.title` | The page's `h1`. A page whose `h1` is the display (a landing page with no separate title) has none, and its display is measured against `type.heading` |
+| `type.heading` | Section headings, `h2` |
+| `type.subheading` | `h3` and below |
+| `type.lead` | An opening paragraph set apart from the body |
+| `type.body` | Running reading copy |
+| `type.supporting` | A standfirst, a dek, a description under a title — reading copy one tier quieter |
+| `type.ui` | Control text: buttons, menu rows, inputs, tabs |
+| `type.label` | Tags, badges, field labels, micro-labels |
+| `type.meta` | Dates, captions, counts, read times, footnotes |
+| `type.code` | Inline and block code, wherever literal code appears. Paths, URLs, IDs and hostnames stay in the text face unless they are code the reader will type |
+| `type.data` | Numerals that must align — tables, prices, stats. Often `type.ui` or `type.body` plus tabular figures rather than its own size |
+
+Families: `family.text`, `family.display` (only if different), `family.ui` (only if different — interface text beside a serif reading face), `family.mono`.
+Weights: `weight.regular`, `weight.strong`. Two optional ones, each only where the preset allows it: `weight.medium`, a third weight above `weight.strong` for headings on a dense screen, only where a project records a job the other two can't carry, and `weight.display`, the display tier's own weight, never reused below it.
+
+## Colour
+
+Owned by the colour guide. Every colour role has a value per theme.
+
+**Text** — a strictly descending ladder, each tier clearing 4.5:1 on the worst surface it lands on:
+
+| Role | Job |
+|---|---|
+| `text.primary` | Headings, body, the active state |
+| `text.secondary` | Supporting copy, inactive-but-readable UI |
+| `text.tertiary` | The lowest readable tier: meta, placeholders that carry meaning, timestamps |
+| `text.inverse` | Text on an inverted surface (a tooltip, a filled button) |
+| `text.on-accent` | Text on the accent colour |
+| `text.link` | Only if links differ from surrounding text. Many systems leave this out on purpose |
+
+A project may slot extra tiers between secondary and tertiary (the Glass preset has `muted` and `quiet` there). Each extra tier must be distinguishable from its neighbours *and* clear 4.5:1 — which is the constraint that usually limits a light theme to four or five.
+
+**Icons** have no tier of their own: they take the tier of the label they sit beside, or one below it.
+
+**Surfaces:**
+
+| Role | Job |
+|---|---|
+| `surface.page` | The page background |
+| `surface.subtle` | A secondary page region — a sidebar, a footer band |
+| `surface.raised` | A component's own surface — a card, an input, a menu |
+| `surface.hover` | That surface, hovered |
+| `surface.pressed` | That surface, pressed or active |
+| `surface.selected` | A persistent selected state, distinct from hover. Under product and expressive, the accent tint colour law 7 defines |
+| `surface.floating` · `surface.overlay` | A floating or modal level's own surface, where it differs from `surface.raised` — usually only in dark themes, where elevation is shown by lightening |
+| `surface.inverse` | Tooltips, toasts, solid-filled chrome |
+
+**Lines and fills:**
+
+| Role | Job |
+|---|---|
+| `border.default` | The edge of an object — a card, an input |
+| `border.control` | The edge of an input or control, which must reach 3:1 to be seen as interactive. May share a token with `border.default` only if that already reaches 3:1 |
+| `border.hover` | That edge, hovered or emphasised |
+| `border.divider` | A rule between groups inside one object or column. May share a token with `border.default` |
+| `border.layered` | A border or divider on an unknown or translucent backdrop — must be translucent itself |
+| `fill.strong` | A solid fill: a filled button, a marker, a toggle's on state |
+| `fill.strong-hover` | That fill, hovered |
+| `mark` | Decorative marks with no text: bullets, dots, inactive rail markers. Not held to text contrast |
+
+**Signal:**
+
+| Role | Job |
+|---|---|
+| `focus` | The focus ring. Must hit 3:1 against every surface it can land on |
+| `accent` · `accent.hover` | The brand or action colour, if the system has one, and its hovered state. `accent` may share a token with `focus` |
+| `status.danger` · `status.warning` · `status.success` · `status.info` | Each a pair — `status.<name>.fg`, a foreground read as text, and `status.<name>.bg`, a background tint — plus `status.<name>.solid` where a filled control needs it (a destructive button) |
+| `exception.<name>` | A deliberate chromatic spend outside the accent, always named after what it's *for*; a hue family answering one question is `exception.<question>.<member>` (`exception.type.task`, `exception.area.<name>`, `exception.person.<n>`), each listed in `DESIGN.md` |
+
+## Layout
+
+Owned by the layout guide.
+
+| Role | Job |
+|---|---|
+| `measure.reading` | The width of running text |
+| `measure.wide` | Content that isn't prose but should still align — grids, tables |
+| `measure.app` | An application shell's content area, if there is one |
+| `measure.form` | Forms and settings inside a panel, so controls stay near their labels |
+| `measure.frame` | The wider frame that the reading column and its rails are both anchored to, so the gap between them holds as the window grows |
+| `measure.rail` | The width of a rail in the outer margin — a table of contents, an aside |
+| `gutter` | Horizontal page padding at the smallest width (Material's *margin*) |
+| `grid.columns` · `space.column` | A column grid's count per breakpoint, and the gap between columns (Material's *gutter*). Product and expressive only, and only where unlike blocks sit side by side |
+| `target.min` | The smallest hit area a control may have, per pointer: never under 24px fine or 44px on touch, which a preset's dial may raise |
+| `space.tight` | Inside a group — a label and its value, items in a list |
+| `space.group` | Between groups inside a section |
+| `space.section` | Between sections |
+| `space.heading-above` · `space.heading-below` | The asymmetric pair around a heading. Their *ratio* is the rule, not their values |
+| `radius.pill` · `radius.small` · `radius.control` · `radius.card` · `radius.container` | Smallest to outermost. Concentric corners obey inner = outer − padding; anything away from a corner takes a radius for its size |
+| `hairline.chrome` · `hairline.object` · `rule.emphasis` | Divider weight inside chrome, the edge of an object, and a deliberate heavy rule (a quote bar, a focus ring) |
+| `z.below` · `z.raised` · `z.popover` · `z.dismiss` · `z.nav` · `z.overlay` · `z.toast` · `z.skip-link` | The stacking ladder, low to high (layout law 7) |
+| `bp.<name>` | Breakpoints, named for what changes at them, not for devices |
+
+## Surfaces and depth
+
+Owned by the depth guide.
+
+| Role | Job |
+|---|---|
+| `elevation.flat` | In the page — separated by a border or a surface step, no shadow |
+| `elevation.raised` | Lifted slightly — a card that can be picked up, a sticky header |
+| `elevation.floating` | Over content, dismissable — menus, popovers, hover cards |
+| `elevation.overlay` | Over everything, modal — dialogs, sheets |
+| `material.opaque` | A solid surface |
+| `material.translucent` | A see-through surface, if the system uses them at all. Tiers, when there are several, are named by how little is known about the backdrop: `.soften` (a backdrop meant to stay recognisable), `.chrome` (content scrolling under fixed chrome), `.defensive` (anything, including other glass) |
+| `scrim` | The dimming layer behind a modal |
+
+Each elevation level is a *bundle* — a surface, an edge, a shadow and a z-layer. The depth guide checks the bundle, not the parts.
+
+## Motion
+
+Owned by the motion guide.
+
+| Role | Job |
+|---|---|
+| `duration.instant` | Press feedback, focus rings |
+| `duration.micro` | Opacity and colour on hover |
+| `duration.state` | Small state changes: colour, background, icon swaps, small transforms |
+| `duration.popover` | Something small appearing: a hover card, a menu, a chevron |
+| `duration.overlay` | Something large appearing or collapsing: a sheet, a region, a reveal |
+| `duration.route` | A page transition |
+| `duration.theme` | Every colour on the page changing at once — only when the page itself switches theme |
+| `ease.standard` | The one curve almost everything uses |
+| `ease.colour` | For colour-only interpolation, where an overshooting curve would wobble |
+| `ease.exit` · `duration.exit` | Only if exits deliberately use a different curve, or a duration of their own rather than a shorter tier |
+| `ease.floor` | A curve that never passes its target, for tracks carrying a property that can't go below zero (blur, scale to nothing) when `ease.standard` overshoots |
+| `spring.<character>` | Springs named by how they feel — `snappy`, `soft`, `playful` — never by their numbers |
+
+`duration.*` values must increase with the size of the change. That is the one rule a project can't rename away.