Repository navigation
site: one UI spec, a reference hub and concise docs - #74
Merged
Merged
Conversation
The portal draws its heroes and metrics at 48/32/24/22/18px, outside the token scale, so the site cannot render from one source of truth. The owner chose token sizes over shrinking every heading to h1. Two roles join the scale: font.size.display 32/40 and font.size.title 24/32, opened as a proposed decision; the owner sets its status. Every port classifies the four new roles the way it classifies h1 (Windows leaves them unsupported: its PowerToys Markdown surface has no level above h1), and each port's tokenDigest follows the new resolved token set. docs/ui-architecture.md states the site chrome contract the redesign uses. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner asked for the decisions to be regrouped and for duplication and verbosity to go. The index is now one table per topic and the entries follow that order; every id, status, date, heading and Status line is unchanged. Text that repeated another decision or spec/ became a pointer, and contrast figures from the computed report point to exports/contrast.md where the decision did not depend on the exact number. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The README re-told the identity, the decisions and every portal tool's own page; it is now an entry point with a quick start and links. The Phase 6 documents become short records of what was decided and delivered, the visual review and design mode keep their operational steps, and the consumer protocol keeps every rule, format and marker with shorter prose. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Source digests, the full Markdown export, the packaged consumer rules and the form identity follow the condensed decision log and docs. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep color precision and keyboard wrapping semantics while sharing their implementations, clean scratch fixtures, and reserve one primary form action. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Refresh the package closures, generated guide, and source fingerprints after the Node refactor. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner asked for specs without unnecessary verbosity. The 67 component bodies restated frontmatter the site and exports already render (variants, anatomy, tokens, keys, contrast pairs) and quoted contrast ratios by hand, most of them stale since D-026, D-027 and D-033 (button's primary 9.28:1, text-field's placeholder 5.81:1). Bodies now keep purpose, behaviour nuance, precedence, host obligations and non-examples; every heading and States row stays, and every removed fact is traced in the D2 claim ledger. link.md follows accepted D-027: links hover on color.interaction.hover.bg, in the prose, root.bg-hover, the hover stateTokens, the summary and the "ring on the hover fill" contrast pair. text-field.md drops a reason that contradicted D-025. tests/spec-prose.test.js fails when spec prose or a component body names a ratio other than the 3:1, 4.5:1 and 7:1 floors; computed values live in the frontmatter contrast pairs and exports/contrast.md. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Identity, foundations, accessibility, portability, form-patterns and the Figma bridge said several things twice (accessibility restated the focus ring, motion and D-033 rules that foundations owns) and carried computed ratios that had gone stale (the text ladder's raised column since D-027, "6.5 to 7.6:1" for the status hues). Each rule now lives once; the text ladder points at the contrast report and gains the link row. Foundations' "selected + focus-visible" row named the container ring, against its own rule 2 and accepted D-027; it now names the ordinary ring. The type scale lists display 32/40 and title 24/32 as proposed (D-037). Co-Authored-By: Claude Opus 5.5 <[email protected]>
The Claude Code and Codex guides repeated the same update, restore, backup,
state-folder and planning rules word for word; they now live once in
ports/README.md ("Claude Code and Codex installers") and both guides link
there. ports/README.md defers port layout and statuses to
spec/portability.md instead of restating them.
Obsidian and Telegram READMEs are install and use; their IMPLEMENTATION.md
files hold the details, without the duplicates between the two. Obsidian's
heading and bold prose now matches accepted D-033 and its mapping. The
Windows guide links to COVERAGE.md for the five sections it duplicated.
Commands, paths, flags, generated blocks and every string a port test reads
are unchanged; removed facts are traced in the D2 claim ledger.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Outputs of npm run generate after the spec and port-guide condensation: component JSON and briefs, the compact and full exports, the contrast report (link's hover pair now on color.interaction.hover.bg), digests, task inputs and the packaged rules. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The claim ledger showed that a few removed sentences were the only record of a number or an operational step: D-036's 4.31 link limit and D-030's operator ratio, the pinned GITHUB_SHA build rule, the local tool commands and flags, PW_PORT, and some Phase 6 scope lines. They are back in short form. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Digests and exports follow the restored decision text. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Condenses the spec documents, the 67 component bodies and the port guides, removes hand-written contrast ratios (guarded by tests/spec-prose.test.js), aligns link.md with D-027 and adds the D-037 sizes to the type scale. Generated outputs were regenerated after the merge. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The UI build prefixes every themed-controls rule with [data-j3w1-controls], which lifts a :where() rule to the specificity of one class. controls.css loads last, so on the portal it repainted every .button as an input box: on /builder/ and /patterns/validation-recovery/ the primary computed to the input fill. The foundation's font reset outranked .button's font size too. Generic control looks now match only controls without a class, keeping each rule's old specificity; a classed control belongs to its component. Co-Authored-By: Claude Opus 5.5 <[email protected]>
copy.ts read a button's label on every click, so a second click within 1.5 s saved "copied" as the label for good. The label is now captured once per button and the reset timer restarts. Copy feedback lived in six scripts, two of which wrote to the clipboard directly; clipboard.ts is again the only writer and reports to a button or a status region. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Portal, tool and 404 pages used three shells with their own chrome: a filled current item and a three-column link grid on phones instead of the spec's drawer, type at 48/32/24/22/18 px outside the scale, literal spacing, and at least eight button looks, several of them <a> elements. SiteLayout is now the only shell outside /reference/. Its rail is the canonical sidebar-nav at 240 px, which becomes the canonical drawer below 900 px (and stays in the page without JavaScript); breadcrumbs, the skip link, link cards, tables and fields are canonical classes at comfortable density. The command palette trigger sits in the top bar. Calls to action are .link.link-standalone; actions are .button in one tone each, with one primary per view. Heroes and metrics use the D-037 display size, page titles the title size; chrome.css takes every length from tokens. 404 no longer ships the inspector's token data. Hash links to the reference go straight to reference/#… instead of through the home page's JavaScript (R-d). usage.spec.js reads the revision stamp from the shell's page header. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Without site.css the port catalogue's five-column tables wrapped each cell to a few characters at 360px and /ports/ grew to 2.4 million pixels. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Regroups spec/decisions.md into six topic index tables with entries in topic order (ids, rows, headings and Status lines unchanged), and condenses the README, agents/consume.md and seven docs. Generated outputs were regenerated after the merge. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner, reviewing the redesigned site: "keep components compacted by default, j3w1/theme default is compacted components" and "if it is not stated that default is compaction, then standardize it in j3w1/theme". Nothing stated it: the generated CSS defined the density variables only under [data-density], so an unset subtree fell back to per-component values that were the comfortable ones. The generated token CSS and recipe scopes now carry the compact values on :root and on the bare .j3w1-recipe wrapper, copied bundles and consumer examples render compact, foundations.md and the site chrome contract state the default, and tests/density-default.test.js pins it. Co-Authored-By: Claude Opus 5.5 <[email protected]>
… tone slots Dialog buttons, the empty-state action and the file-input button each re-declared a button tone with their own box, hover and focus rules, so the same tone looked slightly different per component. The box, the tone slots (--_bg --_fg --_border --_bg-hover --_fg-hover --_bg-active --_border-active --_ring) and the real states now live once in partials/button.css, which button.css and these components import. Declared roles are unchanged; forced states stay in each component's file, where the matrix and validation read them, and rewrite the same slots. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Owner review: the chrome uses the default compact density (D-038), not comfortable. Token paths no longer break mid-word: they wrap only at their dots below 600px and stay on one line above it, and table.css now gives the first column the sticky position table.md requires below 600px. Copy actions sit in a bar attached under their example and source. Builder buttons take their label width (button.md), and the workflow panel no longer leaves gaps for an empty status line and hidden actions. The verification report's reset button mirrors the canonical secondary tone. Co-Authored-By: Claude Opus 5.5 <[email protected]>
- 19 compact component stylesheets drew the focus ring at +2px through --space-2; D-006 and foundations require --focus-offset (−2px). The same files spelled var(--focus-ring) out longhand. - Links hovered on hover.bg-strong; accepted D-027 says hover.bg. The reference contents (.toc) did the same. - Density fallbacks assumed comfortable; the default is compact (D-038). - Removed duplicate root rules (avatar, button-group, chart, description-list, file-browser, kbd), unused template classes, the unused .badge-empty, .skip-link-demo, .toc-title and .tag-heritage, a second .skip-link in site.css, and Swatch.astro, which nothing imported. Range and segmented control drew their forced disabled state on a class no markup uses; it now targets their input. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The *-control template drew its buttons as input boxes with no hover or pressed state, so a Save in a button group, a Close in the command palette or a Retry in an error state looked like neither of the button tones. Owner decision (via the coordinator): button-type template controls are the canonical secondary button through the shared partial; input-type controls keep their input look. The nine components' frontmatter now maps the button parts to the secondary roles and declares the label contrast at rest and on hover; their States rows say so. Co-Authored-By: Claude Opus 5.5 <[email protected]>
button.css and dialog.css now import the shared button partial, and the recipe generator rejected any @import. Recipe styles are read through the same cssSourceClosure the package build uses, so relative imports inside site/src/styles are inlined before scoping, and every imported file joins the recipe's source digests. Approved by the coordinator for worker B. button.css keeps its own background transition: the workbench's motion inspector reads it from the component file. Co-Authored-By: Claude Opus 5.5 <[email protected]>
NonExamples' item literals and the Workbench's fallback, presets, tables and motion endpoints were single lines of 250-700 characters. Each property and element now has its own line, in the prevailing two-space style. Rendered SVG strings are unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]>
On one page of every SiteLayout template, at desktop and narrow width, every visible button outside specimens, live examples, density-scoped previews and the choice renderer's parts must be a canonical .button with the canonical compact box (D-038); no <a> may carry a button class; and /builder/ and /patterns/validation-recovery/ must show exactly one filled primary in color.action.primary.bg. The last check fails on 707f110, where controls.css repainted every primary as an input box (R-b). Co-Authored-By: Claude Opus 5.5 <[email protected]>
…overns The owner wants no unnecessary verbosity in the specs. D1's regroup left rule detail that lived only in decisions, so the log stayed near 7,000 words. Each decision now keeps what was chosen, why, the rejected alternatives worth remembering and its Status line, with "Rule:" naming the section that holds the rule. Computed ratios are left to exports/contrast.md. Moved: the D-014 preview geometry and hover-popup rules to identity.md beside the exception; the D-035 accent ceiling to foundations Surfaces; the D-029 heritage primitive rules to foundations Terminal slots; the D-036 limits to accessibility Limitations; the D-018, D-035 and D-036 port classification facts to portability Native ports; the D-032 shared palette hosts and CE Devbox prompt to terminal.md Portability. D-031's CI rules stay in D-031: no spec section or guide owns CI. Also corrects accessibility.md: the evidence fixture records the page's declared profile and density when the test ends, not the starting configuration (tests/browser/evidence-fixture.mjs). Index rows, headings, anchors and every Status line are unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner asked for no unnecessary verbosity in the docs, and this was the one guide not yet condensed (1,892 words). It now covers install and pin, import and register, the themed-control enhancement, frameworks, forms, copy and upgrade notes, with 4.0.0 (D-033) added to the release notes that stopped at 3.0.0. Keyboard details point to the component pages that own them. The density note follows D-038: compact is the default and comfortable is an opt-in, where the guide still offered both as equal choices. Marker blocks and every kept command and path are unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep legacy anchors readable, scope matrix states and share lazy search and token data so readers load only the detail they need. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Resolve source CSS before Astro relocates its build modules, and audit visible chrome controls without excluding the compact document root. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The fragment audit now checks actual destinations across pages, while immutable historical specimens retain their original links and bytes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep palette assertions on visible commands and discover the comparison route from reviewed sources so test collection works before the build. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Generation is current after the final source refinements; no generated bytes changed. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Check token references and visible normative content where the complete specifications now live, and retain compact command categories. Co-Authored-By: Claude Opus 5.5 <[email protected]>
All generated outputs are current; generation produced no drift. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep shell visibility rules outside specimen clones, restore the isolated preview inset, and measure final transition colours on the smaller detail pages. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Generated files remain current after the rendering fixes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Visit every component and moved normative page with the original rule set and exclusions so the compact hub does not narrow accessibility coverage. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Generation stays current after retargeting the full accessibility scan. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Give scrollable code and API regions keyboard access, render existing whitespace glyphs as graphics in shared specimens and package examples, and retain full reflow and motion coverage after the split. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The normative demos can use more components than package examples, so discover their nested roots before building the scoped matrix CSS. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Generated artifacts remain current after the matrix dependency fix. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Give the new component rendering checks explicit scopes and retain the original readable-description constraints in the token explorer. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The package description and the Astro config comment still called the site a single page; the reference is now a static hub whose detail lives on per-component, contrast and decision pages. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…al pending) Folds the check loop, hex-swatch and evidence rules into shorter statements without dropping a rule, adds packages/ui/dist/ and the agents/consume.md marker block to the generated list (R-k: generators.mjs rebuilds them), names PW_PORT and the pinned GITHUB_SHA build, and replaces "single-page visual reference" with the /reference/ hub and its detail pages. The CE Meta integration section is byte-identical. The owner approves the exact text before this ships (G2). Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep selection focus on the ordinary ring, record computed contrast limits, refresh focus dependencies and make calendar removal reversible. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Publish the corrected component contracts, contrast pairs and packaged styles from their sources. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Selected items take the ordinary focus ring (D-027), breadcrumbs and toast links hover on hover.bg, frontmatter waivers carry no computed ratios, code-editor declares its syntax-on-selection limits as waived pairs, settled spec defects are fixed, focus dependency lists match the CSS, and the demo calendar's Remove offers Undo. Co-Authored-By: Claude Opus 5.5 <[email protected]>
D-037's display and title tokens carry proposed status, so agents use-and-report them instead of treating them as approved. The seven published /implement/ anchors are real headings again and a dist test pins them. The no-<details> guard follows the content to every reference, component and token page. The density test proves the saved density reaches a specimen after reload. Each Tools page has its own rail icon. Restores four rules the condensing pass lost (host override scope, contract review on upgrade, the shared specimen renderer, the task-kit output parent), removes two duplicated rules and dead CSS, reuses the shared contrast, hex and hash helpers, and rewraps the last lines over 1,000 characters without changing their output. The changelog declares the release's changes, including the per-value copy buttons now living on each token's page. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The owner accepted D-037 at the G2 authority review, so the four display and title tokens are approved and export as plain "use". At the same review the owner approved the condensed AGENTS.md as proposed in 60b2b94, confirmed D-038 as accepted, and kept the release under [Unreleased]. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The delta reviews found three overstatements. Token pages copy a token's path and CSS variable, not its value; the reference grids still copy values. Only ordinary controls and rows focus at -2px, under D-006, which is still proposed. The decision log keeps its historical measurements and some rules with no other home, so the documentation entry describes reduced repetition rather than one statement per fact. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
One UI spec for the whole site, a light reference hub, and docs that say each thing once.
What changes
SiteLayoutbuilt from the components it documents: sidebar-nav (an icon rail from 900 to 1279px, a drawer below 900px), breadcrumbs, search, cards, tables and fields. Every action is a canonical.buttonin one of the four tones, with one primary per view. Every call to action is a.link.link-standalone. A browser guard checks every portal route: buttons of one tone share one computed box, and no<a>carries button classes.focus.offset(−2px), per foundations rule 2 (D-006, proposed); containers and invalid fields keep their own offsets. Selected items take the ordinary dashed ring, and links hover oninteraction.hover.bg(D-027). Composite actions reuse the button tone slots, and field parts share one partial.:rootand bare recipe wrappers carry the compact values.data-density="comfortable"opts in.font.size.display32/40 andfont.size.title24/32, classified by every port./reference/is a static hub. State matrices, token tables and computed contrast pairs move to/components/<id>/. The contrast report, decision log and fixtures move to their own/reference/pages, and/ports/gets one page per port. Every published anchor still resolves; a dist test checks the frozen list of pre-change anchors. Normative content stays static, with no JavaScript or<details>. The reference token tables lose their per-row copy buttons; token pages copy the path and CSS variable, and the surface and text grids still copy values./reference//ports//tokens/Words:
spec/decisions.md7,258 → 5,592; README hand-written text 3,056 → 1,167; component spec bodies 29,648 → 21,311; port guides 15,116 → 12,786.Regressions fixed, each with a test
The Node tests for R-a, R-l and R-m were shown failing on
main; the browser tests for the others were not replayed againstmain.@j3w1/[email protected].Checks
npm run test:allsteps, browser part at 6 workers): validate, check,npm test, pinned build,test:dist,ui:consumers,test:uion Chromium and Firefox (42 passed), the browser matrix (543 passed, 0 failed, 225 skipped by project), andverification:report,verification:checkandtest:verificationall pass.Not run
ui:reportandui:publish-evidencelocally: WebKit cannot launch on this host (missing system libraries). The full-matrix workflow dispatch on this branch covers them.Open calls for the owner (unchanged here)
surface.code/surface.terminalandcolor.code.bg/color.terminal.bgdescribe the same background with different values.focus.ring-on-fillwould replace about 24 written-out rings.code.line-number.surface.canvastrack is still under 3:1.Version stays 4.0.0; the changes are under [Unreleased].
🤖 Generated with Claude Code