@pugi/cli 1.0.0-alpha.236 → 1.0.0-alpha.239

package/skills/od-craft/references/typography-hierarchy.md

@@ -0,0 +1,167 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/typography-hierarchy.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# Typography hierarchy craft rules
+
+Shared hierarchy contracts that layer on top of `typography.md`. This file does
+not repeat scale ranges or tracking values — those live in `typography.md`.
+This file defines how hierarchy *behaves*: entry points, rhythm, tension, and
+the conditions under which controlled violations are allowed. This contract
+applies per-surface (a page with multiple pacing resets may establish new
+primaries at intentional intervals), not globally.
+
+> Opt in via `od.craft.requires: [typography, typography-hierarchy]`.
+> Aesthetic-specific variants (e.g. `typography-hierarchy-editorial`) extend this.
+
+---
+
+## The core contract
+
+Every typographic surface must satisfy all three:
+
+1. **One dominant entry point.** The eye needs a place to start. One element
+   wins the hierarchy — not two, not three. If everything competes, nothing leads.
+2. **Intentional rhythm between levels.** Hierarchy is not a list of sizes.
+   It is the *contrast* between them. Adjacent levels that are too close
+   in scale, weight, or spacing produce a flat, undifferentiated surface.
+3. **Recoverable information flow.** Hierarchy may be inverted, collapsed,
+   or disrupted — but a reader must still be able to reconstruct the content
+   structure without re-reading. If they can't, it's chaos, not tension.
+
+---
+
+## Hierarchy vectors
+
+Scale is one lever. Use all five.
+
+| Vector | What it controls | Hierarchy direction |
+|---|---|---|
+| Scale | Size contrast between levels | Large → small reads as primary → secondary |
+| Weight | Mass contrast between levels | Heavier reads as primary (see Controlled violations for weight inversion) |
+| Spacing | Breathing room around an element | More space = more visual importance |
+| Tracking | Tension and velocity | Tighter = faster; wider = ceremonial, slower |
+| Alignment | Relationship to the grid/edge | Breaking alignment signals importance |
+
+No single vector is required. A heading may lead through spacing alone if
+scale is deliberately suppressed. A pull quote may lead through alignment
+break. Identify which vectors are active and make sure at least two are
+working in the same direction for the dominant element.
+
+---
+
+## Semantic role ≠ visual role
+
+Allowed. Not an error. Not a lint violation.
+
+An `<h1>` may render visually quieter than a nearby `<p>` if the
+composition requires it. Body copy may behave like display typography.
+A label may visually outrank a heading.
+
+**The condition:** information flow must remain intact. A user who reads
+linearly must still understand what is important, what supports it, and
+what is incidental — regardless of which element "wins" visually.
+
+---
+
+## Hierarchy rhythm — the two failure modes
+
+### Flat hierarchy
+
+Everything lands at roughly the same visual weight. The surface reads as
+a wall. Usually caused by:
+- Scale steps that are too close (e.g. 18 / 20 / 22 px for three levels)
+- Weight used only once (everything is regular, or everything is medium)
+- Uniform spacing between all elements
+
+Fix: increase contrast between levels. Use at least two vectors simultaneously.
+
+### Noise hierarchy
+
+Too many elements fighting for dominance. Everything is bold, large, or
+accented. The eye has no resting point and no path.
+
+Fix: promote one element deliberately. Demote everything else — including
+things that feel important. Hierarchy is relative, not absolute.
+
+---
+
+## Controlled violations
+
+The following are explicitly allowed when the three core contracts are met:
+
+| Violation | Allowed when |
+|---|---|
+| Body copy at display scale | It is the intended entry point and nothing else competes |
+| Heading rendered lighter than body | Intentional visual inversion with intact information flow |
+| Zero scale contrast between levels | Hierarchy is carried entirely by spacing or tracking |
+| No heading-level element visible | Hierarchy is emergent from layout/spacing alone |
+| Primary-level spacing applied to secondary element | Creates deliberate tension while maintaining information flow |
+
+**"Information flow remains intact" safeguards:**
+- DOM/reading order still matches content meaning (no layout inversion breaks narrative)
+- Proximity groups the inverted element with its parent/context
+- Only one primary exists in the visual region (no competing co-primaries)
+- A quick scan can identify entry point / support / incidental roles without rereading
+
+---
+
+## Spacing as hierarchy
+
+Spacing is a full hierarchy vector. A typographic level can be elevated
+entirely through surrounding whitespace without changing its size or weight.
+
+Rules:
+- Space above an element signals its relationship to what came before.
+- Space below an element signals its relationship to what follows.
+- An isolated element with large surrounding space reads as display-level
+  regardless of its font size.
+- Uniform spacing between all elements destroys spatial hierarchy.
+
+---
+
+## Three-level working model
+
+Most surfaces can be mapped to three functional levels:
+
+| Level | Role | Typical vectors |
+|---|---|---|
+| **Primary** | Entry point. One at a time per visual region; long-form surfaces may re-establish at intentional pacing resets. | Scale, spacing, or alignment break |
+| **Secondary** | Structure. Subdivides or supports primary. | Weight, scale step, or tracking shift |
+| **Tertiary** | Incidental. Labels, captions, metadata. | Scale reduction, weight reduction, or positive tracking |
+
+More than three visible levels above the fold is usually a composition problem,
+not a hierarchy opportunity. Collapse or demote before adding a fourth level.
+
+**Long-form surfaces:** May re-establish a primary at intentional pacing resets
+(e.g. a new section with its own headline and breathing room). Never maintain
+two simultaneous primaries within the same visual region.
+
+---
+
+## Anti-patterns
+
+- **Graduated weight ladder** — regular → medium → semibold → bold → extrabold,
+  each level one step heavier. Reads as a default scale, not authored hierarchy.
+  Weight should jump, not step.
+- **Uniform section spacing** — every section gap is the same value. No
+  hierarchy information is carried by spacing. Vary it deliberately.
+- **Heading as the only hierarchy vector** — the heading is large and bold;
+  everything else is flat. The heading does all the work. This is a sign
+  that spacing and tracking are not being used as vectors.
+- **Symmetrical emphasis** — two elements receive equal visual weight as
+  co-primaries. Pick one. The other becomes secondary.
+- **Size-only hierarchy** — all contrast is in font size alone. Weight,
+  spacing, tracking, and alignment are uniform across levels. Fragile —
+  any layout constraint that collapses the size contrast destroys the hierarchy.
+
+---
+
+## Lint
+
+- [ ] One element is unambiguously dominant above the fold.
+- [ ] At least two hierarchy vectors are active on the dominant element.
+- [ ] No two adjacent levels share the same scale, weight, AND spacing.
+- [ ] Spacing between levels varies — at least one gap is ≥1.5× the others or
+      represents one typographic scale step (e.g. one token unit like `gap-md` vs `gap-sm`). (guidance)
+- [ ] Semantic/visual role inversions remain structurally readable.
+- [ ] Flat hierarchy: scale steps between levels are ≥1.25× apart OR compensated by a weight or spacing jump. (guidance)
+- [ ] Noise hierarchy: no more than one element reads as primary above the fold.

package/skills/od-craft/references/typography.md

@@ -0,0 +1,124 @@
+<!-- Vendored from nexu-io/open-design@78d5637cb49d (craft/typography.md), Apache-2.0, Copyright 2026 Open Design contributors. Modified by Pugi: this header line added; the text below is otherwise verbatim. Paths it names (apps/daemon/src/lint-artifact.ts, pnpm lint:craft, od.craft.requires) are upstream's, not Pugi's: the Pugi port of the linter is packages/opencode/src/session/design-lint.ts. See NOTICE.md in the skill root. -->
+
+# Typography craft rules
+
+Universal typography rules that apply on top of any `DESIGN.md`. The
+active design system decides *which* fonts; this file decides *how* they
+behave at every size.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT) — distilled and re-tuned for OpenDesign's token system.
+
+## Type scale
+
+Use a multiplicative scale (1.2 or 1.25). Cap at 6–8 sizes per artifact.
+
+| Role | Range |
+|---|---|
+| Display | 48–72 px |
+| H1 | 32–48 px |
+| H2 | 24–32 px |
+| H3 | 20–24 px |
+| Body | 15–18 px |
+| Small | 13–14 px |
+| Caption | 11–12 px |
+
+## Line height (leading)
+
+| Text size | Line height |
+|---|---|
+| Display / H1 (≥32 px) | `1.0`–`1.2` (tight) |
+| Body (15–18 px) | `1.5`–`1.6` |
+| Small (≤14 px) | `1.5` |
+
+### CJK overrides — these are not optional
+
+The table above is Latin leading. Latin display type can go to `1.0`
+because the ascender/descender slack inside the em box keeps lines
+apart. **CJK glyphs fill the em box**, so the same value makes
+consecutive lines touch, and multi-line Chinese headlines visibly
+collide.
+
+| Text size | Latin | CJK |
+|---|---|---|
+| Display / H1 (≥32 px) | `1.0`–`1.2` | **`1.3`–`1.4`** |
+| Body (15–18 px) | `1.5`–`1.6` | `1.7`–`1.8` |
+
+The CJK floor has **no upper size tier**. It applies to every heading
+level, including the **cover / hero main title** — the single biggest
+headline on a deck's first slide. A Chinese cover title at 72 px,
+96 px, or larger, especially one split into multiple lines with
+`<br>`, is still CJK display text: set `line-height: 1.3`–`1.4` on
+it, never the Latin `1.0`–`1.2`. At 96 px a `1.05` leading makes the
+two lines of a Chinese cover headline visibly collide. This is the
+single most common violation, so check the cover main title first.
+
+Negative tracking is Latin-only for the same reason: CJK is already
+set on a fixed em grid, so `-0.02em` on a Chinese headline crowds the
+glyphs instead of tightening the word. Use `0` for CJK display text.
+
+When one artifact mixes both — an English kicker over a Chinese
+headline is the common case — set the tight Latin values on the Latin
+element only. Do not inherit them onto the CJK block from a shared
+parent rule.
+
+## Letter-spacing — the rule that makes or breaks craft
+
+This is the single most-skipped rule in AI-generated design. **No
+exceptions.**
+
+| Context | Letter-spacing |
+|---|---|
+| Body text (14–18 px) | `0` (default) |
+| Small text (11–13 px) | `0.01em` to `0.02em` (positive) |
+| UI labels and button text | `0.02em` |
+| **ALL CAPS** | **`0.06em` to `0.1em` (required)** |
+| Headings 32 px+ | `-0.01em` to `-0.02em` |
+| Display 48 px+ | `-0.02em` to `-0.03em` |
+
+ALL CAPS without positive tracking looks cramped and amateur. Display
+text without negative tracking looks loose and weak. These two failures
+are the most reliable AI-slop tells.
+
+The `0.06em` floor is not arbitrary: it is the empirical lower bound
+that print and web typographers have converged on for uppercase
+tracking (cf. Bringhurst's *Elements of Typographic Style* §3.2.7,
+which recommends 5–10% of the em for caps; modern screen practice
+rounds the lower end to 0.06em). Anything tighter and the counters
+collide on screen; the upper bound `0.1em` keeps the word from
+disintegrating into letters.
+
+## Font pairing
+
+- Maximum 2 typefaces per artifact (display + body, or one variable face
+  used at multiple weights).
+- Always declare a system fallback chain. If the active `DESIGN.md`
+  ships a webfont URL, the fallback must still produce a coherent look.
+- Never set `font-family: system-ui` alone on a heading — that is the
+  textbook AI default; always pair it with an intentional first choice.
+
+## Line length
+
+Limit body copy to **50–75 characters** per line. In CSS:
+`max-width: 65ch` is a safe default.
+
+## Three-weight system
+
+Most well-crafted UIs use exactly 3 weights:
+- **Read** (400 / 450) — body copy
+- **Emphasize** (510 / 550) — UI text, labels, navigation
+- **Announce** (590 / 600) — headlines, buttons
+
+Weight 700+ is rarely needed. If your design uses bold for "emphasis on
+emphasis," it likely lacks weight discipline elsewhere.
+
+## Common mistakes (lint these)
+
+- ALL CAPS without `letter-spacing` ≥ `0.06em`.
+- Display text (≥32 px) without negative tracking (Latin only — see the CJK overrides).
+- CJK display text at Latin leading (`≤1.2`), which makes the lines overlap.
+- Multi-line CJK cover / hero titles (72–96 px+, e.g. split with `<br>`) below `1.3` line-height.
+- Negative tracking applied to CJK text.
+- More than 3 type sizes visible above the fold.
+- Mixed serif and slab on the same screen without a clear role split.
+- Body copy in `text-align: justify` (creates rivers; never use on the web).

package/skills/od-reference-design-contract/NOTICE.md

@@ -2,7 +2,8 @@
 
 These skills are part of Sofia's (designer) skill pack. They help her go from a
 brief to a design system to the clickable HTML prototype that the customer
-approves at the plan gate (`.pugi/artifacts/prototype.html`, BACKLOG AO).
+approves at the plan gate (`.pugi/artifacts/prototype.html`, BACKLOG AO), and,
+since 2026-10-17, carry the craft rules every build turn is held to.
 
 The skill pack generator copies this file and `LICENSE-APACHE-2.0` into every
 vendored skill directory, so each one carries its attribution wherever it is
@@ -10,21 +11,40 @@ baked.
 
 Both upstream projects are licensed under the Apache License, Version 2.0. The
 full licence text is in `LICENSE-APACHE-2.0` next to this file. The LICENSE file
-of each repository was checked on 2026-10-04 before anything was copied.
-Neither repository ships a NOTICE file, so this file is the attribution.
+of each repository was checked before anything was copied (2026-10-04 and
+2026-10-17). Neither repository ships a NOTICE file, so this file is the
+attribution.
 
 ## nexu-io/open-design
 
 - Source: https://github.com/nexu-io/open-design
-- Commit: 53231d40b778d88eba23f35547bf99485d3ae9fc (2026-09-30)
 - Licence: Apache-2.0, "Copyright 2026 Open Design contributors"
 - The upstream `skills/README.md` says skills are Apache-2.0 unless their own
-  `LICENSE` says otherwise. Neither directory copied here has its own licence.
+  `LICENSE` says otherwise. No directory copied here has its own licence.
+- Commit 53231d40b778d88eba23f35547bf99485d3ae9fc (2026-09-30) for the two
+  prototype skills; commit 78d5637cb49da07e81314d1544b5fc6d37c95084 (v0.25.1,
+  2026-10-16) for the craft rules and the two ports below.
 
 | Pugi skill | Upstream path | Files copied |
 |---|---|---|
 | `od-web-prototype` | `design-templates/web-prototype/` | `SKILL.md`, `assets/template.html`, `references/layouts.md`, `references/checklist.md` |
 | `od-reference-design-contract` | `skills/reference-design-contract/` | `SKILL.md`, `references/checklist.md` |
+| `od-craft` | `craft/` | all twelve documents, as `references/<name>.md`: `README.md`, `accessibility-baseline.md`, `animation-discipline.md`, `anti-ai-slop.md`, `color.md`, `form-validation.md`, `laws-of-ux.md`, `rtl-and-bidi.md`, `state-coverage.md`, `typography-hierarchy-editorial.md`, `typography-hierarchy.md`, `typography.md` |
+
+Upstream attributions kept inside those files: `craft/` is adapted from
+referodesign/refero_skill (MIT, © Refero Design); the "Adapted from" lines
+stay where upstream put them.
+
+### Ports (derivative works, Apache-2.0 §4), not copies
+
+| Pugi file | Upstream source | What changed |
+|---|---|---|
+| `packages/opencode/src/session/design-lint.ts` | `apps/daemon/src/lint-artifact.ts` | The seven P0 checks and the external-image advisory are kept; the finding shape is local; it runs over a workspace (source and `dist/`) rather than one artifact body; Tailwind utility-class forms of each sin are added; the deck, `data-od-id`, all-caps tracking and raw-hex checks are dropped; the sans-display check fires only when a serif display token is bound. The daemon's analytics were never in this file. |
+| `packages/opencode/src/scaffold/design-direction.ts` | `apps/daemon/src/prompts/directions.ts` | The five schools are kept as postures; labels no longer name other brands; palettes are hex; faces are the Google fonts the starters link; two directions added; no question form (the direction is decided by the model, never asked of the customer). |
+| `packages/plugin-pugi-personas/src/craft-digest.ts` | `craft/*.md` | A condensed summary written by Pugi from the twelve documents. |
+
+Nothing ported touches the network: open-design's PostHog / Langfuse telemetry
+lives in its apps, none of which were taken.
 
 ## nexu-io/html-anything
 
@@ -45,6 +65,12 @@ Neither repository ships a NOTICE file, so this file is the attribution.
   `web-prototype` would collide across the two sources.
 - One HTML comment was added under each frontmatter block. It names the source,
   the commit and these changes.
+- `od-craft/SKILL.md` is written by Pugi (upstream has no skill wrapper for
+  `craft/`; its daemon injects the files per `od.craft.requires`). Each
+  `references/*.md` begins with one added HTML comment naming the source
+  commit and stating that the rest is verbatim; the text below it is
+  unchanged, including upstream's references to its own paths
+  (`apps/daemon/src/lint-artifact.ts`, `pnpm lint:craft`).
 - Example files (`example.html`, `example.md`) were not copied.
 - Every other byte of the copied files is unchanged.
 
@@ -54,3 +80,6 @@ Two upstream rules conflict on purpose. The output file is
 `.pugi/artifacts/prototype.html`, not `index.html`. Photos are Pexels CDN URLs
 taken from Anvil `/v1/images`, not copies in the project, because the console
 renders the prototype from a single document.
+Where a craft rule names open-design's tokens (`var(--accent)`), the starter's
+own token scheme (`src/globals.css` bare HSL components, `src/theme.css`
+typefaces) wins.

package/skills/od-web-prototype/NOTICE.md

@@ -2,7 +2,8 @@
 
 These skills are part of Sofia's (designer) skill pack. They help her go from a
 brief to a design system to the clickable HTML prototype that the customer
-approves at the plan gate (`.pugi/artifacts/prototype.html`, BACKLOG AO).
+approves at the plan gate (`.pugi/artifacts/prototype.html`, BACKLOG AO), and,
+since 2026-10-17, carry the craft rules every build turn is held to.
 
 The skill pack generator copies this file and `LICENSE-APACHE-2.0` into every
 vendored skill directory, so each one carries its attribution wherever it is
@@ -10,21 +11,40 @@ baked.
 
 Both upstream projects are licensed under the Apache License, Version 2.0. The
 full licence text is in `LICENSE-APACHE-2.0` next to this file. The LICENSE file
-of each repository was checked on 2026-10-04 before anything was copied.
-Neither repository ships a NOTICE file, so this file is the attribution.
+of each repository was checked before anything was copied (2026-10-04 and
+2026-10-17). Neither repository ships a NOTICE file, so this file is the
+attribution.
 
 ## nexu-io/open-design
 
 - Source: https://github.com/nexu-io/open-design
-- Commit: 53231d40b778d88eba23f35547bf99485d3ae9fc (2026-09-30)
 - Licence: Apache-2.0, "Copyright 2026 Open Design contributors"
 - The upstream `skills/README.md` says skills are Apache-2.0 unless their own
-  `LICENSE` says otherwise. Neither directory copied here has its own licence.
+  `LICENSE` says otherwise. No directory copied here has its own licence.
+- Commit 53231d40b778d88eba23f35547bf99485d3ae9fc (2026-09-30) for the two
+  prototype skills; commit 78d5637cb49da07e81314d1544b5fc6d37c95084 (v0.25.1,
+  2026-10-16) for the craft rules and the two ports below.
 
 | Pugi skill | Upstream path | Files copied |
 |---|---|---|
 | `od-web-prototype` | `design-templates/web-prototype/` | `SKILL.md`, `assets/template.html`, `references/layouts.md`, `references/checklist.md` |
 | `od-reference-design-contract` | `skills/reference-design-contract/` | `SKILL.md`, `references/checklist.md` |
+| `od-craft` | `craft/` | all twelve documents, as `references/<name>.md`: `README.md`, `accessibility-baseline.md`, `animation-discipline.md`, `anti-ai-slop.md`, `color.md`, `form-validation.md`, `laws-of-ux.md`, `rtl-and-bidi.md`, `state-coverage.md`, `typography-hierarchy-editorial.md`, `typography-hierarchy.md`, `typography.md` |
+
+Upstream attributions kept inside those files: `craft/` is adapted from
+referodesign/refero_skill (MIT, © Refero Design); the "Adapted from" lines
+stay where upstream put them.
+
+### Ports (derivative works, Apache-2.0 §4), not copies
+
+| Pugi file | Upstream source | What changed |
+|---|---|---|
+| `packages/opencode/src/session/design-lint.ts` | `apps/daemon/src/lint-artifact.ts` | The seven P0 checks and the external-image advisory are kept; the finding shape is local; it runs over a workspace (source and `dist/`) rather than one artifact body; Tailwind utility-class forms of each sin are added; the deck, `data-od-id`, all-caps tracking and raw-hex checks are dropped; the sans-display check fires only when a serif display token is bound. The daemon's analytics were never in this file. |
+| `packages/opencode/src/scaffold/design-direction.ts` | `apps/daemon/src/prompts/directions.ts` | The five schools are kept as postures; labels no longer name other brands; palettes are hex; faces are the Google fonts the starters link; two directions added; no question form (the direction is decided by the model, never asked of the customer). |
+| `packages/plugin-pugi-personas/src/craft-digest.ts` | `craft/*.md` | A condensed summary written by Pugi from the twelve documents. |
+
+Nothing ported touches the network: open-design's PostHog / Langfuse telemetry
+lives in its apps, none of which were taken.
 
 ## nexu-io/html-anything
 
@@ -45,6 +65,12 @@ Neither repository ships a NOTICE file, so this file is the attribution.
   `web-prototype` would collide across the two sources.
 - One HTML comment was added under each frontmatter block. It names the source,
   the commit and these changes.
+- `od-craft/SKILL.md` is written by Pugi (upstream has no skill wrapper for
+  `craft/`; its daemon injects the files per `od.craft.requires`). Each
+  `references/*.md` begins with one added HTML comment naming the source
+  commit and stating that the rest is verbatim; the text below it is
+  unchanged, including upstream's references to its own paths
+  (`apps/daemon/src/lint-artifact.ts`, `pnpm lint:craft`).
 - Example files (`example.html`, `example.md`) were not copied.
 - Every other byte of the copied files is unchanged.
 
@@ -54,3 +80,6 @@ Two upstream rules conflict on purpose. The output file is
 `.pugi/artifacts/prototype.html`, not `index.html`. Photos are Pexels CDN URLs
 taken from Anvil `/v1/images`, not copies in the project, because the console
 renders the prototype from a single document.
+Where a craft rule names open-design's tokens (`var(--accent)`), the starter's
+own token scheme (`src/globals.css` bare HSL components, `src/theme.css`
+typefaces) wins.