@noir-ai/skills 1.16.0 → 1.17.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @noir-ai/skills
 
-The native `noir-*` skill pack (27 builtins plus 1 integration) and a copy-and-validate compiler. `noir init` / `noir sync` emit it idempotently for hosts with a skill surface: Claude uses `.claude/skills/`; Cursor uses `.cursor/rules/*.mdc`. There is no plugin or marketplace.
+The native `noir-*` skill pack (32 builtins plus 1 integration) and a copy-and-validate compiler. `noir init` / `noir sync` emit it idempotently for hosts with a skill surface: Claude uses `.claude/skills/`; Cursor uses `.cursor/rules/*.mdc`. There is no plugin or marketplace.
 
 Part of the **[Noir](https://github.com/agaaaptr/noir#readme)** toolkit — the discipline, context, and memory layer for any agentic CLI.
 

package/builtin/{noir-code-hygiene → noir-codebase-audit}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: noir-code-hygiene
-description: Use when writing or reviewing comments, docstrings, summaries, or documents — keep every line carrying something a reader can act on. Use when the user says "clean this up", "this reads like machine output", or asks for a comment sweep. Do NOT use for layout (indentation, quoting, line length); this is about what the text says.
+name: noir-codebase-audit
+description: Use when auditing a codebase, a diff, or a report for what to cut and what reads machine-written — name over-engineering to delete, harvest deliberate debt, and de-slop the prose. Use when the user says "audit this", "what should I cut", or asks for a comment sweep. Do NOT use for layout, formatting, or linting; this is about what to cut and what the text says.
 metadata:
   category: meta
   version: 1.0.0
@@ -10,32 +10,86 @@ references:
   - examples.md
 ---
 
-# noir-code-hygiene
+<!-- noir-hygiene: exempt -->
 
-Text that reads as machine-generated fails in a small number of ways, and every
-one of them is a sentence a reader cannot act on. The ten defects below are
-those ways, each as a Tell (what it looks like), a Why (what it costs a reader)
-and a Fix (what to write instead). Four of them — restating, stale text, jargon,
-unstated assumptions — are judgements a person makes; the rest are mechanical
-enough that the quality gate checks them itself.
+# noir-codebase-audit
+
+An audit finds what a reader pays to understand twice. It runs in four passes
+over the same code: over-engineering to delete, deliberate debt to record,
+prose to de-slop, and the mechanical defects that make text read as generated.
+The last pass is also enforced by the quality gate, so this guidance and the
+gate agree on what counts as noise.
 
 ## When to use
 
-- Writing or reviewing a comment, docstring, summary, or document that a reader will meet without the context its author had.
-- Sweeping a file, a diff, or a report for text that reads as generated.
-- The user says "clean this up", "this reads like machine output", or asks for a comment sweep.
+- Auditing a codebase, a diff, or a report for what can be deleted.
+- Harvesting deliberate debt markers into a ledger a later change can read.
+- Sweeping comments, summaries, or documents that a reader will meet without the context their author had.
+- The user says "audit this", "what should I cut", "this reads like machine output", or asks for a comment sweep.
 - Reviewing your own output before handing it back: comments and summaries are where these defects concentrate.
-- **Do NOT use:** for layout (indentation, quoting, line length), or as a substitute for a formatter or a type checker. This is about what the text says, not how it is drawn.
+- **Do NOT use:** for layout (indentation, quoting, line length), for linting or formatting, or as a substitute for a type checker. This is about what to cut and what the text says, not how it is drawn.
 
 ## Procedure
 
-1. **Read the text as somebody who did not write it.** For each sentence, ask what a reader learns that the code, the diff, or the line above does not already say. A sentence that teaches nothing is the one to delete.
-2. **Delete before rewriting.** Most defects end at deletion: a divider, a restated line, an empty label, a fact that is no longer true. Rewriting a comment that should not exist only makes the noise longer.
-3. **Keep what the code cannot say.** The reason a value is what it is, the invariant a caller depends on, the condition that would break the order, the precondition. When only a restatement would be left, the comment is finished.
+1. **Run the four passes in order.** Delete over-engineering first, record deliberate debt, de-slop the prose, then sweep the mechanical defects. Deletion first shrinks the surface the later passes have to read.
+2. **Delete before rewriting.** Most findings end at deletion: a wrapper, a restated line, a fact that is no longer true. Rewriting a thing that should not exist only makes the noise longer.
+3. **Keep what the code cannot say.** The reason a value is what it is, the invariant a caller depends on, the ceiling a shortcut accepted and the trigger that retires it. When only a restatement would be left, the comment is finished.
 4. **Name things in the reader's terms.** Replace a codename, or a shorthand that resolves only against a planning document, with the mechanism it stood for. State the path, the command, or the precondition instead of assuming the reader knows it.
 5. **Run the gate.** `noir skills lint` over a skill body, `noir doctor` over a repository. Fix every fail-tier finding; read a warn-tier one as a question about the line rather than a rule to satisfy.
 
-## Tell / Why / Fix
+## Over-engineering audit
+
+One finding per line: name the thing, then delete it. When a finding needs a
+second sentence to explain, the deletion was not obvious enough to do today.
+
+- A wrapper around one standard-library call that adds nothing — delete the wrapper.
+- An interface with one implementation — delete the interface until a second one exists.
+- A factory that builds one product — delete the factory.
+- A configuration knob nobody has changed and nobody will — delete the knob.
+- A branch, flag, or parameter written "for later" with no caller — delete it; later can write it.
+- A dependency pulled in for something a few lines would have covered — drop the dependency.
+- A test that asserts the implementation rather than the behavior — rewrite it against the behavior, or delete it.
+
+## Deliberate debt
+
+A shortcut that cuts a real corner and names its ceiling is debt a later reader
+can pay off; a shortcut that names nothing is a slow bug wearing a comment. The
+`noir-debt:` marker records the first kind.
+
+Write the marker as a source comment with both halves, the ceiling and the
+condition that justifies the upgrade: `noir-debt: global lock; per-account locks
+once throughput matters`. The second half is not optional: `noir-debt: global
+lock` names the ceiling but no trigger, so nobody knows when to pay it.
+
+Harvest the markers into a ledger grouped by file, one line per marker, with
+the ceiling, the trigger, and the file it sits in. Read the ledger before the
+next change in that file. A marker whose trigger has arrived is not debt to
+keep; it is the work to do now.
+
+## Anti-slop
+
+De-sloping removes the vocabulary a generator reaches for first. Three lists,
+three treatments.
+
+- **Banned** — delete on sight, replace with a plain verb or noun: delve, utilize, leverage, facilitate, elucidate, embark, endeavor, encompass, multifaceted, tapestry, testament, paradigm, synergy, holistic, catalyze, juxtapose, realm, landscape, myriad, plethora.
+- **Rationed** — at most one per paragraph, and only when it names something concrete: robust, comprehensive, seamless, cutting-edge, innovative, streamline, empower, foster, enhance, elevate, optimize, scalable, pivotal, intricate, profound, resonate, underscore, navigate, cultivate, bolster, galvanize, cornerstone, game-changer.
+- **Filler** — delete the frame, write the claim: "it is important to note that", "needless to say", "a testament to", "in the realm of", "serves as a".
+
+## Humanizer tells
+
+Three prose tells mark a writer trying to sound human rather than be useful.
+
+- **Em-dash density.** More than two em-dashes in one paragraph is a tell; the em-dash is the punctuation a generator leans on when a period would do. Split the sentence, or use a parenthetical.
+- **Hedging openers.** "It is worth mentioning", "it should be noted", "it goes without saying" frame a claim before making it. Delete the frame and make the claim.
+- **The not-X-but-Y contrast.** "This is not a bug but a feature" reads written because the first clause exists only to set up the second. State the second clause alone.
+
+## The mechanical defects
+
+The ten defects below are the shapes a generator produces, each as a Tell (what
+it looks like), a Why (what it costs a reader) and a Fix (what to write
+instead). Four of them — restating, stale text, jargon, unstated assumptions —
+are judgements a person makes; the rest are mechanical enough that the quality
+gate checks them itself.
 
 ### Decorative separators and banners
 
@@ -181,11 +235,11 @@ The rules themselves are one table in the skills package, and each entry carries
 
 ## Verification
 
-- [ ] Every sentence kept carries something the code, the diff, or the line above does not.
+- [ ] Every line kept carries something the code, the diff, or the line above does not.
+- [ ] Every finding of the over-engineering pass names one thing to delete, and it is gone.
+- [ ] Every `noir-debt:` marker names a ceiling and a trigger, and the ledger lists them.
 - [ ] No divider, no restatement, no ordinal marker, no empty label survives the pass.
 - [ ] Every fact stated beside the code is true of the code as it stands now.
-- [ ] Every codename or shorthand is replaced by the mechanism it stood for.
-- [ ] The path, the command, and the precondition are stated rather than assumed.
 - [ ] `noir skills lint` (skill body) or `noir doctor` (repository) reports no fail-tier finding.
 
 ## Notes

package/builtin/{noir-code-hygiene → noir-codebase-audit}/references/examples.md

@@ -1,4 +1,4 @@
-<!-- Worked examples for the noir-code-hygiene skill.
+<!-- Worked examples for the noir-codebase-audit skill.
 
      This file exists to show the shapes the rules forbid, so it must contain
      them. It therefore declares the exemption the rules honour with the marker

package/builtin/noir-dataviz/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: noir-dataviz
+description: Use when the user asks for a chart, graph, plot, dashboard, or any data visualization — pick the chart form before the palette, apply the four color jobs and the legibility floors, then set mark sizes and ship a text alternative for every chart. Do NOT use for general UI design (noir-design) or picking a visual style (noir-design-reference).
+metadata:
+  category: domain
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-dataviz
+
+Charts in one surface should hold together as a single system: pick the parts in a fixed order — form first, color last, marks between. Color is the last decision, not the first, because a chart that works in grayscale still works, and a chart that leans on color alone falls apart the moment the hue is removed.
+
+## When to use
+
+- The user asks for a chart, graph, plot, dashboard, or any data visualization, in any medium (HTML, SVG, matplotlib, plotly, d3, or a rendered image).
+- A screen needs a stat tile, sparkline, heatmap, legend, axis, or tooltip, and no chart standard is set.
+- The question is about chart colors, series palettes, or how many colors a chart needs.
+- Do NOT use for general UI layout, styling, or screen design. noir-design owns those.
+- Do NOT use for picking an aesthetic, a style, or the token schema. noir-design-reference owns those.
+
+## Procedure
+
+1. Pick the chart form first, before any color. Match the data shape to a form and write the form down:
+   - Compare categories → bar chart.
+   - Show change over time → line chart.
+   - Show parts of a whole → stacked bar or donut.
+   - Show how values are distributed → histogram.
+   - Show the relationship between two measures → scatter plot.
+   A palette must not drive this choice; the data shape does.
+
+2. Pick the one color job that matches the data. There are four, and each encodes a different relationship:
+   - Categorical: distinct hues, equal lightness, and a fixed order the whole chart family reuses. No series may read as more important than another.
+   - Ordinal: one hue ramped from light to dark in steps, so rank reads as lightness.
+   - Sequential: one hue stepped from its 100 to its 700, where a larger value is a darker step.
+   - Diverging: two hues that meet at a neutral midpoint; the midpoint is the meaningful center (zero, the mean, a threshold), and both sides darken away from it.
+
+3. Check the legibility floors before rendering. Each pair of series colors needs enough separation to read as different data: hold at least a delta-E of 15 between any two series, and at least 3:1 luminance contrast between any data element and its background (text stays at 4.5:1). Keep the separation color-vision-safe: never let red versus green be the only difference between two series — add a shape, dash, label, or lightness step instead. Keep categorical hues inside OKLCH lightness 0.45 to 0.75 on light surfaces and 0.50 to 0.70 on dark surfaces, with chroma no lower than 0.08, so a hue that reads on white still reads on near-black.
+
+4. Set the mark grammar. Minimums keep marks visible and clickable at any size:
+   - Bars: at least 8 px wide, with a gap smaller than the bar itself.
+   - Lines: at least 2 px of weight so a line reads as data, not a hairline.
+   - Markers: at least 8 px across so a point stays visible and hittable.
+   - Gridlines: light and behind the data, never competing with it.
+   - Axes: hairline weight in a muted color; the frame supports the data, it does not star.
+
+5. Add the accessibility twin. Every chart ships a table or a text alternative that carries the same numbers, so the chart stays useful when the image is not there. Never let color be the only signal: pair every color with a label, shape, or pattern so the chart still reads in grayscale.
+
+For example, a monthly revenue chart maps time to a line, uses a single hue ramped light to dark, adds a table of the same twelve numbers under the SVG, and relies on the line and its point markers, not its hue, to carry the trend.
+
+## Verification
+
+- [ ] The form is chosen and written down before any color decision.
+- [ ] The color job is named and matches the data relationship (one of the four).
+- [ ] Series colors clear a delta-E of 15 and 3:1 contrast against the background.
+- [ ] Red versus green is never the only separator between two series.
+- [ ] Bars, lines, and markers meet their minimum sizes; gridlines are light; axes are hairlines.
+- [ ] Every chart has a table or text alternative, and no signal rests on color alone.
+
+## Notes
+
+- A form chosen first survives a palette change; a palette chosen first does not survive a form change.
+- Reuse the project's existing palette before inventing a parallel one.
+- In dark mode, keep the same four jobs but re-derive the light-to-dark direction so the contrast floors still hold.
+
+## When done → next skill
+
+→ noir-design for general UI layout and styling. → noir-design-reference for a style or palette lookup.

package/builtin/noir-debt/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: noir-debt
+description: Use when the user asks "what did we defer", "list the shortcuts", "debt ledger", or mentions noir-debt. Grep the repo for the noir-debt markers, then group them by file into a ledger that names each marker's ceiling and upgrade trigger. Do NOT use to fix the debt (the owning task does that), for a general read-only codebase search (noir-exploring), or as a whole-repo audit (noir-codebase-audit owns that pass).
+metadata:
+  category: meta
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-debt
+
+Harvest every `noir-debt:` marker in the repository into a ledger grouped by file. Each entry names the marker's ceiling and the trigger that retires it, so a later change can pay the debt back instead of rediscovering it.
+
+## When to use
+
+- The user asks "what did we defer", "list the shortcuts", "debt ledger", or mentions noir-debt.
+- Before changing a file, to see which markers inside it have a trigger that has already arrived.
+- **Do NOT use** to fix the debt itself; the owning task pays it. For a general read-only codebase search, use `noir-exploring`; this skill only greps `noir-debt:` markers and builds the ledger. For the whole-repo over-engineering and prose pass, use `noir-codebase-audit`.
+
+## Procedure
+
+1. **Find the markers.** Grep the repo for `noir-debt:` in source comments, for example: `grep -rn "noir-debt:" .`. Narrow the include patterns to the languages present.
+2. **Read each marker's two halves.** A marker names a ceiling and the condition that justifies the upgrade, for example: `// noir-debt: global lock, per-account locks when throughput matters`. A marker with only a ceiling is incomplete; list it as such rather than inventing a trigger.
+3. **Group by file.** Order entries by path, then line. One line per marker: file, line, ceiling, trigger.
+4. **Print the ledger to stdout.** Keep it copyable: one line per marker, no summary paragraphs. A marker whose trigger has already arrived is flagged in its group as due now.
+
+## Verification
+
+- [ ] Every `noir-debt:` marker in the repo appears in the ledger, grouped by file.
+- [ ] Each entry carries the ceiling and the trigger, or is flagged when the trigger half is missing.
+- [ ] Entries are one line each, ordered by file then line.
+- [ ] Markers whose trigger has arrived are called out as due.
+
+## Notes
+
+- The ledger is read-only output; writing it to a file or paying the markers belongs to the owning task.
+- A marker without a trigger cannot be paid back on time; report it as incomplete rather than completing it silently.
+- Read the ledger before the next change in a file, so a due marker becomes the work of that change.
+
+## When done → next skill
+
+→ `noir-executing-plans`, or the owning task, to pay a marker whose trigger has arrived. Or `noir-codebase-audit` for the full audit pass.

package/builtin/noir-design/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: noir-design
+description: Use when the user says "design this", "style this", "make it look good", or "frontend design" — commit to one bold aesthetic, run the anti-template checks, and resolve the precedence ladder before any styling code. Do NOT use for token system mechanics (noir-design-reference) or charts and data visualization (noir-dataviz).
+metadata:
+  category: domain
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-design
+
+Set one committed aesthetic before any styling code, and spend the boldness in a single place. A page that is half brutalist and half glassy reads as unsure; a page that is one thing, done deliberately, reads as designed.
+
+## When to use
+
+- The user says "design this", "style this", "make it look good", or "frontend design".
+- A UI brief is vague and needs a direction before anyone writes CSS.
+- An existing screen looks like a template and needs a distinct point of view.
+- Do NOT use for token system mechanics, the style inventory, or the palette schema. noir-design-reference owns those.
+- Do NOT use for charts, graphs, or data visualization. noir-dataviz owns those.
+
+## Procedure
+
+1. Commit to one bold aesthetic. Pick a single style from noir-design-reference (neobrutalism, editorial, glassmorphism, and the rest) and carry it through every decision. Spend the boldness once, on an oversized headline or one saturated accent, and keep everything else quiet so that one moment lands.
+2. Run the anti-template check. Reject a design that leans on these ready-made tells:
+   - The cream background with terracotta accents, the near-black with acid-green pairing, and every other two-color recipe that shows up unchanged across AI output.
+   - A small tracked ALL-CAPS eyebrow above every headline.
+   - The generic card: a soft drop shadow, a hairline border, and content floating in it with no structural reason.
+   - Monospace type used as decoration on labels that are not code.
+   - A call-to-action label that trails an arrow character, repeated on every link.
+   These are not wrong because they are common; they are wrong because they read as unexamined. If one earns its place, keep it and say why.
+3. Resolve the precedence ladder, in this order: the user's instruction and brand guide first, the project's existing design system second, the accessibility floor third, and the brief's own suggestions last. When two levels conflict, the higher one wins.
+4. First pass: define tokens before code. Name the colors, spacing, radius, and type scale as variables before writing a component. Reuse the project's existing tokens when they exist; do not invent a parallel system. For example, a landing page might commit to editorial type with one oversized headline, and keep every other element quiet. noir-design-reference carries the 16-token semantic palette when no system exists.
+5. Build component-first, responsive by default, and accessible. One component, one file, one job. Mobile layout first, wider breakpoints after. Semantic elements, keyboard reachability, a visible focus indicator, and a label on every input.
+   - Wide tables and code blocks scroll inside their own container (`overflow-x: auto`); the page body never scrolls horizontally.
+   - Buttons and links are real `<button>` and `<a>` elements, never a `<div onClick>`.
+   - Optimistic updates feel faster, but they roll back on failure; a failed action must undo itself visibly.
+6. Second pass: review against the brief. Read the original request again and check that every visible choice answers it. Cut anything that exists only because it looked good.
+
+## Verification
+
+- [ ] One aesthetic is named and carried through every screen.
+- [ ] The anti-template list was checked, and any surviving cliché has a stated reason.
+- [ ] The precedence ladder was applied top-down with conflicts resolved in order.
+- [ ] Tokens are defined before components, reusing the project's system when it exists.
+- [ ] Every interactive element is keyboard-reachable and labeled; text meets WCAG AA contrast.
+
+## Notes
+
+- Boldness is a budget, not a default. One strong choice per screen is enough; two competing choices cancel out.
+- When a design system already exists, follow it. This skill directs the aesthetic, not the token plumbing.
+
+## When done → next skill
+
+→ noir-design-reference when a style name, palette, or font pairing needs looking up. → noir-verifying when the UI must be checked against the spec.

package/builtin/noir-design-reference/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: noir-design-reference
+description: Use when the user asks "what style should I use", names a style like "neobrutalism" or "glassmorphism", says "pick a style", or needs a design reference — consult references/design.md and return the matching style's tokens, cost, and accessibility floor. Do NOT use for generating assets or for general layout questions.
+metadata:
+  category: domain
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - design.md
+---
+
+# noir-design-reference
+
+The style inventory. When a design question needs a named style, its tokens, its build cost, its accessibility floor, a semantic palette, a rule ladder, a font pairing, or a motion budget, this skill reads references/design.md and returns the relevant part. It answers the "which style, and what does it cost" question; noir-design answers the "what should this screen commit to" question.
+
+## When to use
+
+- The user asks "what style should I use", "pick a style", or "design reference".
+- The user names a style (neobrutalism, glassmorphism, and the rest) and wants its tokens.
+- A screen needs a semantic color palette or a font pairing and none exists yet.
+- Do NOT use for generating images, icons, or any binary asset. This skill names large assets as pointers, never as files.
+- Do NOT use for general layout questions or for deciding a direction. noir-design owns those.
+
+## Procedure
+
+1. Read the question for what is being asked: a named style, an open choice between styles, a palette, a font pairing, or a motion budget.
+2. Open references/design.md and find the section that matches.
+3. For a named style, return that style's era, tokens, cost, accessibility floor, and use-and-avoid guidance.
+4. For an open choice, shortlist two or three styles by build cost and context, and present each in one line so the user can commit.
+5. For tokens, pull the 16-token semantic palette and fill it with the chosen style's colors, light and dark.
+6. For the rest, pull the relevant rung from the UX rule ladder, the font-pairing guidance, or the motion tiers. For example, asking for neobrutalism returns its era, tokens, cost, floor, and fit.
+
+## Verification
+
+- [ ] The returned guidance came from references/design.md, not from memory.
+- [ ] A named style came back with cost and accessibility floor, not only its look.
+- [ ] An open choice names the trade-off (cost, floor, fit), not just a list of names.
+- [ ] No asset is generated; anything large is named as a pointer.
+
+## Notes
+
+- This file is a reference: consult it, quote from it, and hand the decision back to noir-design.
+
+## When done → next skill
+
+→ noir-design to apply the chosen direction. → noir-verifying to check the finished screen against the spec.

package/builtin/noir-design-reference/references/design.md

@@ -0,0 +1,200 @@
+# Design reference — styles, tokens, rules, fonts, motion
+
+This file is the inventory noir-design-reference consults. It holds the style taxonomy, the semantic color palette, the UX rule ladder, the font-pairing guidance, and the motion tiers. It is a reference, not a playbook: noir-design decides the direction; this file supplies the raw material for that decision.
+
+## How to read this file
+
+- For a named style, read its entry under the taxonomy and return era, tokens, cost, accessibility floor, and fit.
+- For an open choice between styles, compare the Cost and Accessibility floor lines first, then the fit.
+- For color, copy the 16-token palette and fill it with the chosen style's colors.
+- For any other rule, find the rung or tier that matches and quote it.
+
+Cost is the effort to build the style well and keep it accessible. Low means a day of CSS. Medium means several days with fallbacks. High means bespoke assets or platform-specific work.
+
+## Style taxonomy
+
+Fourteen styles. Each entry names the era, the signature in one line, the tokens that carry it, the cost, the accessibility floor, and when it earns its place.
+
+### neobrutalism
+
+**Era**: 1990s web revival, popular again from 2020.
+**Signature**: flat blocks with thick borders and hard offset shadows; the layout owns its grid.
+**Tokens**: saturated primaries on off-white or near-black; radius 0; hard shadow with no blur (4px 4px 0); a 2px to 4px solid border, often black; bold grotesque display type.
+**Cost**: low to medium. The borders and shadows are cheap CSS; the real work is restraint, because every element shouting at once collapses the style.
+**Accessibility floor**: contrast is strong by default, but pure saturated color pairs can drop below 4.5:1, so check text pairs. The offset shadow must never be the only focus indicator.
+**Use**: playful, opinionated, or developer-facing products. **Avoid**: quiet, clinical, or financial surfaces.
+
+### glassmorphism
+
+**Era**: early 2020s frosted-panel trend.
+**Signature**: translucent panels that blur what sits behind them, edged with a thin light border.
+**Tokens**: semi-transparent white fill at 10 to 20 percent opacity; backdrop blur; a 1px border in a lighter tone; radius 16 to 24px; a soft diffuse shadow; light or mid-weight sans type.
+**Cost**: medium to high. backdrop-filter is expensive on low-end GPUs and needs a solid fallback behind it.
+**Accessibility floor**: translucency cuts text contrast, so a glass panel needs a darker scrim or a solid fallback. Never let blur carry legibility alone.
+**Use**: dashboards and cards over imagery, where depth sells the hierarchy. **Avoid**: dense data tables and forms, where the blur adds cost without clarity.
+
+### neumorphism
+
+**Era**: 2019 soft-UI experiment.
+**Signature**: elements that look extruded from the background, built from two shadows on a matching surface.
+**Tokens**: background and element share one color; radius 12 to 20px; paired shadows, one light and one dark offset, with no border; low-contrast monochrome type.
+**Cost**: low to build, high to keep accessible.
+**Accessibility floor**: the near-identical tones give weak affordance and poor contrast, so interactive elements need a stronger hover and pressed state, and text needs 4.5:1 against its surface.
+**Use**: decorative control panels and demos. **Avoid**: anything a user must operate quickly, and every form.
+
+### claymorphism
+
+**Era**: 2021 playful 3D-soft look.
+**Signature**: puffy, rounded, toy-like surfaces with an inner top highlight and a soft outer shadow.
+**Tokens**: pastel or mid-tone fills; radius 24 to 40px; a bright inner highlight near the top; a soft outer shadow; a minimal border; rounded friendly type.
+**Cost**: medium. Shadow layering and gradient work add up, and each state needs its own pass.
+**Accessibility floor**: pastels often fall under 4.5:1 on white, so text needs a darker ink, and interactive clay elements need a clear pressed state.
+**Use**: kid-friendly products, onboarding, and empty states. **Avoid**: enterprise dashboards and data-dense screens.
+
+### skeuomorphism
+
+**Era**: mid-2000s realism, the era before flat design.
+**Signature**: digital elements that imitate physical materials such as leather, paper, brushed metal, and glass.
+**Tokens**: realistic gradients and textures; heavy inner and outer shadows; beveled borders; ornament; type that matches the object's period.
+**Cost**: high. Texture and lighting assets are bespoke, and every state needs its own art.
+**Accessibility floor**: texture must not sit behind text without a solid scrim, and imitation depth must not replace labels and focus states.
+**Use**: niche realism where the metaphor teaches the interface, such as music gear, note apps, and games. **Avoid**: general product UI, where texture fights the content.
+
+### minimalism
+
+**Era**: timeless reduction with Swiss design roots.
+**Signature**: the fewest elements needed, with whitespace carrying the hierarchy.
+**Tokens**: one accent color on a neutral background; radius 0 to 8px; no shadow or a hairline shadow; a hairline or no border; restrained type on a strong grid.
+**Cost**: low to build, high to keep disciplined.
+**Accessibility floor**: low contrast is the common failure, so keep text at 4.5:1 or better, and never let whitespace be the only grouping cue a screen reader can rely on.
+**Use**: editorial, documentation, and developer tools. **Avoid**: playful or child-facing products that need warmth.
+
+### brutalism
+
+**Era**: raw early-web ethos, revived around 2016.
+**Signature**: deliberately unrefined defaults: system fonts, default link colors, and exposed structure.
+**Tokens**: system type; browser-default colors; radius 0; visible table borders; no shadows; often a single flat background.
+**Cost**: low to build, medium to keep readable at scale.
+**Accessibility floor**: default contrast is fine, but decorative rawness must not remove focus rings or semantic structure.
+**Use**: personal sites, art projects, and statements. **Avoid**: mainstream products where users expect polish.
+
+### bento grid
+
+**Era**: 2022 dashboard-layout trend descended from Apple-style grid tiles.
+**Signature**: a packed grid of rounded tiles in varied sizes, each holding one piece of content.
+**Tokens**: neutral card fills; radius 16 to 24px; a hairline border; a soft shadow; small clear labels; tight padding.
+**Cost**: medium. Responsive grid sizing and fitting content into tiles both take real work.
+**Accessibility floor**: keep each tile's text at 4.5:1, and keep the tab order matching the visual order.
+**Use**: dashboards, landing summaries, and app home screens. **Avoid**: long-form reading, where the grid fragments the text.
+
+### editorial
+
+**Era**: print magazine typography carried onto the screen.
+**Signature**: strong serif display type, a strict column grid, and generous whitespace.
+**Tokens**: serif display with a clean sans body; off-white or paper background; near-black ink; hairline rules; radius 0; no shadows.
+**Cost**: medium. The type pairing and grid discipline are the product.
+**Accessibility floor**: serif display at small sizes loses legibility, so body text stays 16px or larger in a readable face at 4.5:1.
+**Use**: media, culture, publishing, and portfolios. **Avoid**: dense product UI and data tools.
+
+### luxury
+
+**Era**: understated high-end retail aesthetic.
+**Signature**: quiet, spacious, matte surfaces with a single precious accent.
+**Tokens**: a deep neutral or cream background; a gold or deep accent; wide letter-spacing on small caps; hairline borders; soft or no shadow; serif display type.
+**Cost**: medium to high. Photography and spacing carry the product.
+**Accessibility floor**: tiny tracked caps and thin serifs fail 4.5:1, so body text needs a readable size and weight.
+**Use**: fashion, jewelry, hospitality, and premium services. **Avoid**: utilities and tools where speed matters more than mood.
+
+### cyberpunk
+
+**Era**: 1980s neon-noir future.
+**Signature**: glowing neon on dark, with scanlines and high-tech motifs.
+**Tokens**: neon cyan and magenta on deep navy or black; glow shadows; thin borders; mono or tech display type; grid and scanline texture.
+**Cost**: high. Glow effects, texture, and dark-mode-only maintenance all add up.
+**Accessibility floor**: neon on black can bloom and blur, so keep body text bright white or add a dark scrim, and never rely on glow for focus.
+**Use**: games, music, developer tools, and event sites. **Avoid**: long-form reading and anything light-mode-only.
+
+### Y2K
+
+**Era**: late-1990s and early-2000s nostalgia.
+**Signature**: chrome, gradients, and bubbly type from the turn of the millennium.
+**Tokens**: chrome and gradient fills; a pink, blue, and silver palette; glossy bevels; 3D-ish buttons; italic or bubbly display type.
+**Cost**: high. Gradient and bevel art is needed for every state.
+**Accessibility floor**: metallic gradients make text contrast unstable, so put labels on a flat band or scrim and keep touch targets at 44px.
+**Use**: fashion, music, and nostalgia campaigns. **Avoid**: forms, dashboards, and anything with strict legibility needs.
+
+### spatial (visionOS)
+
+**Era**: 2023 glass-and-depth spatial computing idiom.
+**Signature**: frosted glass layers that float at depth with soft light from the environment.
+**Tokens**: frosted glass; subtle depth blur; rounded panels at 20 to 28px; a soft ambient shadow; system sans with generous spacing.
+**Cost**: high. Depth layering and glass are platform-specific.
+**Accessibility floor**: glass over busy scenes needs a scrim, text stays at 4.5:1, and depth must never be the only grouping cue.
+**Use**: spatial and immersive interfaces, premium apps. **Avoid**: plain 2D web where the depth has nothing behind it.
+
+### material / flat
+
+**Era**: Google's 2014 layered-flat system, and the flat design it answered.
+**Signature**: flat color surfaces with soft elevation, grid-aligned and geometric.
+**Tokens**: a small color system; radius 4 to 8px; layered elevation shadows; no gradients; clean sans type.
+**Cost**: low to medium. It is well documented and componentized.
+**Accessibility floor**: elevation shadows are weak affordance, so states need more than a shadow change, and text keeps 4.5:1.
+**Use**: broad product UI, admin tools, and Android-flavored apps. **Avoid**: a bold brand moment, where flat reads as default.
+
+## The 16-token semantic palette
+
+The schema to copy into a project that has no design system. It follows the shadcn and Tailwind naming so it drops into plain CSS variables or Tailwind's color slots. Define every token in light and dark, and never hardcode a hex inside a component.
+
+| Token | Role | Notes |
+|---|---|---|
+| primary | the main brand fill | buttons, links, active states |
+| on-primary | ink and icons that sit on primary | must reach 4.5:1 against primary |
+| secondary | a quieter fill for hover and secondary buttons | a tone of primary or a neutral |
+| on-secondary | ink and icons that sit on secondary | the same 4.5:1 rule |
+| accent | the highlight used once, sparingly | the boldness budget lives here |
+| on-accent | ink and icons that sit on accent | check contrast, since accent is often bright |
+| background | the page background | near-white in light, near-black in dark |
+| foreground | default text and icons on background | 4.5:1 against background |
+| card | fill for cards and panels | one step off background |
+| card-foreground | text and icons that sit on card | 4.5:1 against card |
+| muted | a faint fill for hints and disabled areas | never used for body text |
+| muted-foreground | secondary text on background or card | 4.5:1 for meaningful text |
+| border | hairline rules and input borders | 3:1 against adjacent fills for component boundaries |
+| destructive | the danger fill | buttons that delete or warn |
+| on-destructive | ink and icons that sit on destructive | usually white |
+| ring | the focus ring color | must stand out from background and primary |
+
+An on- token always names the ink that sits on its base token. Keep the list at exactly these 16; a color that appears in one component and nowhere else does not earn a token.
+
+## The UX rule ladder
+
+Check in this order. Each rung outranks the one below it, so a style that fails a higher rung is dropped no matter how it looks.
+
+1. **Accessibility.** 4.5:1 contrast for normal text and 3:1 for large text and component boundaries; every interactive element keyboard-reachable; a visible focus indicator; a label or aria-label on every input; alt text on images. This rung is non-negotiable and comes first.
+2. **Touch and interaction.** 44 by 44px targets with space between them; hover, focus, active, and disabled states on every control; pressed feedback so the user knows the tap registered.
+3. **Performance.** Images sized to their slot and lazy-loaded off-screen; fonts subset or variable; no layout shift from late-loading media; a first paint fast enough that nothing blocks interaction.
+4. **Style selection.** Commit to one aesthetic, as noir-design directs. A style that cannot hold the three rungs above is disqualified.
+5. **Layout and responsive.** Mobile first, widening at breakpoints; an 8px spacing grid so every gap is a step of 8; no horizontal page scroll.
+6. **Typography and color.** 16px minimum body text; a type scale with clear steps; one accent used sparingly; text never sits directly on a busy texture or image.
+7. **Animation.** 150 to 250ms transitions with one purpose each; transform and opacity only; no motion that delays the task.
+8. **Forms and feedback.** A label on every field; errors next to the field they name; empty, loading, error, and success states all present.
+9. **Navigation.** Predictable placement; a visible current state; keyboard operable; no links that lead nowhere.
+10. **Charts and data.** noir-dataviz owns the detail; the floor is a colorblind-safe palette and labelled axes.
+
+## Font pairing
+
+- Two families at most: one display face and one body face. Three is a poster, not an interface.
+- The pairing needs contrast in one dimension: a serif display with a neutral sans body, a grotesque display with its own light cut for body, or one variable family with clear weight and size steps.
+- Body text stays at 16px or larger with a line-height near 1.5; the display face is for headings only.
+- A mono face may join for code and data only, never for paragraphs.
+- Pairs that work: a high-contrast serif display with a neutral grotesque body; a geometric sans display with the same family's regular cut for body; an editorial serif display with a humanist sans body.
+
+## Motion tiers and reduced motion
+
+Pick one tier and keep the whole product in it.
+
+- **None.** Static. For forms, data tools, and anything the user must read carefully.
+- **Subtle.** 150 to 250ms ease-out transitions on hover and focus, with short fades and slides for appearing content. The default for most product UI.
+- **Expressive.** Longer keyframed sequences for heroes and onboarding, with a clear narrative reason to exist.
+
+Every tier wraps behind prefers-reduced-motion: a user who asks for reduced motion gets the None tier regardless of the product's choice. Never animate layout properties that force reflow; transform and opacity are the safe pair.

package/builtin/noir-lazy/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: noir-lazy
+description: Use when the user says "be lazy", "simplest solution", "do less", "yagni", "shortest path", or "minimal solution". Climb the laziness ladder before writing code, and record each deliberate shortcut with a ceiling and a trigger. Do NOT use for non-coding requests, a read-only codebase search (noir-exploring), a project-health diagnostic (noir-doctor), a correctness or security review (noir-verifying or noir-security), or a whole-repo audit (noir-codebase-audit).
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-lazy
+
+Adopt the laziness ladder as the stance for the next coding change: make the smallest change that is still correct, and record every deliberate shortcut with a ceiling and a trigger so a later reader can pay it back.
+
+## When to use
+
+- The user says "be lazy", "simplest solution", "do less", "yagni", "shortest path", or "minimal solution".
+- A request is growing and a smaller version would cover it.
+- **Do NOT use** for non-coding requests, a read-only codebase search (`noir-exploring`), a project-health diagnostic (`noir-doctor`), a correctness or security review (`noir-verifying`, `noir-security`), or a whole-repo audit (`noir-codebase-audit`). This skill is a stance applied while coding, not a review of code that already exists.
+
+## Procedure
+
+1. **Climb the ladder before writing.** Ask the questions in order and stop at the first rung that holds: does this need to exist at all; is it already in this repo; does the stdlib cover it; does the platform; does an installed dependency; can it be one line. Write the minimal code only when every earlier rung failed.
+2. **Fix the root cause, not the symptom.** Before editing a function, find every path that reaches it. Make the change at the shared point so all callers get it in one edit; patching only the reported path leaves the others broken.
+3. **Delete over add.** When two changes produce the same behavior, take the one that removes a line.
+4. **Record deliberate shortcuts.** A cut corner with a known ceiling gets a marker, not silence. For example: `// noir-debt: global lock, per-account locks when throughput matters`. Name both the ceiling and the upgrade trigger; the trigger half is not optional.
+
+## Verification
+
+- [ ] Each rung was considered in order, and the answer is the highest rung that held.
+- [ ] The fix sits at the shared root, not duplicated across callers.
+- [ ] Every deliberate shortcut carries a `noir-debt:` marker with a ceiling and a trigger.
+- [ ] The diff is the shortest change that solves the stated problem, and nothing else.
+
+## Notes
+
+- Lazy means efficient, not careless: read the task and the code it touches before climbing the ladder.
+- Two stdlib options of the same size: take the one that is correct on edge cases, not the flimsier one.
+- State what was skipped and when to add it, in one line, instead of building it now.
+
+## When done → next skill
+
+→ `noir-verifying` to prove the change works. Or `noir-debt` to harvest the markers just written into a ledger.