trykeyline 0.0.0-stage → 0.1.0

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, with an article's title clearly opening the piece (up to 2.25 × body); index and chrome titles lower. Two weights. A sans for interface text is allowed beside a serif reading face. Roles that share a size separate on weight, leading or a rule.
+- **Colour** — near-monochrome. One accent, spent on focus. At most one further chromatic exception, justified structurally. Links usually in the text colour.
+- **Layout** — one reading measure every page shares; rails and asides live outside it. Generous, asymmetric vertical rhythm.
+- **Surfaces** — mostly flat. Elevation reserved for things that float; translucency, if any, only on chrome.
+- **Motion** — short, and only where it makes a change legible. Nothing loops. One set piece, at most, once a session.
+
+## `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. Two weights, strong at 500; labels in sentence case, never uppercase eyebrows. Tabular figures on every number, scoped to numeric elements.
+- **Colour** — near-monochrome neutral ground with a real status palette (danger, warning, success, info), each a foreground/background pair. One accent hue for primary action, focus, selection (the current nav item on a 25% accent tint with accent icon and label) and the primary data series, and no second highlight hue. Brand colour already in the design stays where it has a job. Colour marks what needs a person, not what is finished. Colour for meaning, never for decoration.
+- **Layout** — an app shell rather than a single measure: one navigation surface — a sidebar holding every destination, no top bar repeating it — then content and an optional inspector, every page under its own header bar, forms and settings capped at a form measure. Improving one screen keeps the navigation it has. Sections stack, each opened by its heading, and peer sections are parted by a full-bleed hairline; no bento mosaics or stat tiles. That is the default for a new system; an existing design keeps its own section device (`commands/refine.md`, the limits). Tighter spacing, still grouped asymmetrically. Prose inside the product (settings help, empty-state copy) still sits at a reading measure.
+- **Surfaces** — content on the page, rows parted by hairlines; a data table may take one hairline frame; a settings group that saves together takes a hairline panel; a card only for one object, never a card in a card. A clear, small elevation ladder: flat page, raised cards, floating menus, modal overlays. Hairlines do more work than shadows.
+- **Motion** — shortest of the three. State feedback is near-instant; nothing delays a repeated action. Springs only where something is dragged or thrown.
+
+## `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 for it. Display, title and section headings fluid. Wider scale, still assigned to roles rather than derived from a ratio. Tracking correction matters most here.
+- **Colour** — a brand palette used broadly, with rules about where each colour may go. Chromatic exceptions still named and counted, just more of them.
+- **Layout** — sections may break the reading measure and go full-bleed; the measure still governs any paragraph longer than two lines.
+- **Surfaces** — depth, gradients and translucency allowed as brand material, each with its fallback.
+- **Motion** — longer and more characterful on entrances; exits still get out of the way. A few set pieces, each once. Reduced motion still gets a real alternative.
+
+## `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 `glass/` into `DESIGN.md`, in the project's own names wherever the project already has names, and `glass/<domain>/guide.md` supplies the exact recipes, with drop-in token files and components under each `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 middle weight for dense UI 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 at about 25% over its surface, carrying `accent.ink` at 4.5:1 |
+| `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 that clears 4.5:1 as text, and `status.<name>.bg`, a background tint — plus `status.<name>.solid` where a filled control needs it (a destructive button). Required in product systems, usually absent in editorial ones |
+| `exception.<name>` | A deliberate chromatic spend outside the accent — one per system in editorial, a few in expressive; in product none by default, plus one hue family per question the reader can't answer at a glance, named `exception.<question>.<member>` (`exception.type.task`, `exception.area.<name>`, `exception.person.<n>`), each listed in `DESIGN.md`. Always named after what it's *for* |
+
+## 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, ≈ 640–760px, 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: 24px under a fine pointer, 44px on touch |
+| `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. `z.toast` sits over modals, because a notification about a modal's action must not hide behind it |
+| `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` | 0 — 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.