Shine V4.0.2

Complete the installed-symlink fix across every executable. The portfolio dogfood run found the remaining diagnosis path and expanded the audit to all CLIs.

Shine V4.0.1

Fix installed CLI entry points when invoked through the immutable current-release symlink. Adds a regression test from the portfolio dogfood run.

Shine V4

Shine V4 — art direction, not component accumulation

V4 turns the lessons from the public audit into enforceable behavior. shadcn remains the
composition foundation. Base UI is the greenfield primitive default; React Aria is the escalation
path for complex, internationalized, or accessibility-heavy interaction. Headless UI is not a
replacement for shadcn because it supplies fewer composed patterns and does not solve art
direction.

Release contract

• A reference shortlist contains at most one candidate from a visual family in each scope.
• A composed page supplies the region graph; an atom can only fill a named region.
• Every design spec declares an archetype, image strategy, signature moment, and anti-repetition
  constraint before render.
• Open-source systems may contribute licensed source when they fit the consumer runtime, or a
  cited structure-only blueprint when they do not. Foreign runtimes never enter a shadcn repo just
  to imitate paint.
• Web, editable deck, code-first deck, PDF/report, and email work use output-native proof.
• Existing work begins with a screenshot and evidence-backed diagnosis. Completion requires a
  browser workflow, measure output, and a receipt when the selected reference supports compare.

What the public rebuild tests

The Shine site is the release candidate. Its V3 baseline passed axe and contrast but presented the
product as a narrow technical essay. V4 must preserve those measurable strengths while moving the
real product proof into the hero, showing the before/after at useful size, explaining the open-
source architecture, and making the complete skill available without GitHub.

The artifact pair lives at site/img/shine-v3-before.png and site/img/shine-v4-after.png.
shine-diagnosis.json records the defects that justified the change; site/shine-usability.json
records the executable conversion path.

Shine 3.0 — executable proof

Shine V3: visual proof was not usability proof

Shine got better at detecting visual defects and still let a bad operational surface through. The failure was simple: contrast, accessibility, component structure, and a reference screenshot can prove that a page is coherent. They cannot prove that someone can capture work, understand priority, make a decision, and see the result.

V3 keeps the visual bar and adds an executable usability bar. Every surface now declares the user-facing objects it implements, binds those objects to its selected reference pattern, and exercises the primary job in a real browser. A decorative control, a static dashboard, or a flow with no observable result fails.

The reference corpus remains the source of taste: Shadcn and Untitled UI establish proven structures and interaction vocabulary. Shine now treats them as more than a screenshot target. The selected pattern must be present as working objects in the product, and the product must prove its own job end to end.

The active integration path is deliberately narrower: Shadcn/TanStack for component applications and native, Untitled-shaped contracts where a framework is not present. MUI, Carbon, and Ant are no longer active routing choices.

What shipped

• Real, readable template source, tokens, provenance, and screenshots replace generated DNA stubs.
• shadcn-weekly-board is a complete authored blueprint with working owner/outcome interactions and its own visual proof.
• measure.mjs, usability contracts, and compare.mjs prove composition, workflow, and template-relative pixels at the artifact boundary.
• Cursor and Codex share one immutable release, with fail-closed edit and stop hooks that the doctor exercises rather than merely finding on disk.
• The supported integration surface is intentionally narrow: shadcn/TanStack for component apps and native, Untitled-shaped contracts without a framework.
• The root install and immutable release audit with zero known npm vulnerabilities.

Run the proof between measurement and visual comparison:

node verify/usability.mjs <url-or-page> --contract shine-usability.json --cite <selected-template>

This is not a claim that an automated browser test can replace human judgment. It makes the minimum judgment falsifiable: if the primary workflow is vague, decorative, or broken, Shine cannot call the screen done.

Credit

Shine's shadcn catalog and registry work stands on shadcn/ui, created by shadcn. Thank you for the extraordinary design and engineering work, and for sharing it as an accessible, open-code component system. Shine is an independent project and is not affiliated with or endorsed by shadcn/ui.

Shine 2.0 — visual director

Shine 2.0

Public notes for the V2 release. Architecture internals live in research/world-class-spec.md.

What V1 shipped

A design system an agent cannot quietly leave: DTCG tokens, catalog cite, measure (styles, axe, contrast, composition), doctor as the wiring gate, kit-faithful DNA labels, Wireframe lock.

That was a strong compliance product. It was not yet a director. A Carbon datatable cite could still emit Geist, a zinc sidebar, and eight-pixel radii — and pass.

What V2 ships

Piece	Job
DNA packs	corpus/packs/<id>/ — specimen HTML + expanded DNA + region occupancy. Opening a Preview URL is not enough.
Executable voices	tokens/voices/<family>.css remaps --shine-*. “Retune tokens” is no longer a slogan.
Critic	verify/critic.mjs scores likeness to the pack and names slop. A Carbon cite in shadcn chrome fails.
Lanes	internal · saas · lex · marketing — different quality bars. Glow is marketing DNA and a LEX fail.
DESIGN.md	Written at Wireframe lock. Art direction before code.
Salesforce hosts	Record / console / LWR / email / mobile. Name the host or fail. ~494px component width uses @container.
Slop lint	Cream-serif, indigo-default, purple-glow cannot be pragma-exempted.

Install is unchanged: clone, symlink skill + shine-ux, wire hooks, node verify/doctor.mjs.

Loop

job → lane → cite + DNA pack → DESIGN.md → (Wireframe | Build)
    → voice CSS → measure (compliance) → critic (taste + likeness)
    → ≤3 critic passes → stop

node corpus/cite.mjs queue
node verify/measure.mjs path/to/page.html --cite carbon-datatable --shot /tmp/shot.png
node verify/critic.mjs path/to/page.html --cite carbon-datatable --lane internal
node verify/doctor.mjs

What this is not

• A scraper of Dribbble or Behance
• A promise that every screen will win Awwwards (that bar is marketing / LWR only)
• A second design system. House tokens remain the fallback voice; kit DNA is the default paint.

License: MIT (skill). Tokens and corpus pins stay SPDX-clean; AGPL / Commons Clause kits remain query-only.