Skip to content

feat(ui): add @pretable/ui shared design system package#7

Merged
blove merged 18 commits into
mainfrom
claude/pedantic-joliot-7e6d20
Apr 22, 2026
Merged

feat(ui): add @pretable/ui shared design system package#7
blove merged 18 commits into
mainfrom
claude/pedantic-joliot-7e6d20

Conversation

@blove
Copy link
Copy Markdown
Contributor

@blove blove commented Apr 21, 2026

Summary

Introduces a new workspace package @pretable/ui containing the shared design system for the pretable playground, bench, and upcoming docs apps. No app migration in this PR — playground (Plan B), bench (Plan C), and the new docs app (Plan D) will consume this package in follow-up PRs.

What ships:

  • Design tokens (tokens.css) — editorial (cream/ink/amber) + terminal (dark grid) + severity + syntax palettes, typography stacks, type scale, layout tokens. All --pt-* prefixed.
  • Fraunces font via @fontsource-variable/fraunces (runtime dep, not self-hosted).
  • Five presentational React components:
    • <Receipt> — inline numeric tag chip for body copy
    • <Callout> — cream-hi panel with amber/warn left border, role="note"
    • <CodeBlock> — terminal-surface snippet with optional tabs and copy-to-clipboard
    • <Nav> — 60px sticky header with wordmark, version pill, links, search trigger, GitHub star pill, CTA
    • <Footer> — one-line monospace footer with CI status indicator

Design + plan

  • Spec: docs/superpowers/specs/2026-04-21-pretable-visual-system-design.md
  • Plan: docs/superpowers/plans/2026-04-21-pretable-ui-package.md

Follow-ups folded into this PR

Two small improvements surfaced during review were committed onto this branch since they touch files that only exist here (couldn't be split into separate PRs without stacking):

  • db3fdec chore(ui): tokenize Callout warn tag color — replaced the one hardcoded #7d4f0a with --pt-amber-ink-dark for full token coverage
  • 828414a feat(ui): add semantic role to Calloutrole="note" on both variants (with rationale in the commit about why role="alert" is wrong for persistent docs callouts)
  • 10907d4 fix(ui): prevent Footer CI status from being announced twice — the dot's aria-label duplicated the adjacent visible "ci: {status}" text; now aria-hidden

Test plan

  • 21 unit tests passing (pnpm --filter @pretable/ui test)
  • Typecheck clean (pnpm --filter @pretable/ui typecheck)
  • Lint clean (pnpm --filter @pretable/ui lint)
  • Build emits dist/{index.js,index.d.ts,tokens.css,components.css}
  • Full repo pnpm test green (no regressions in playground/bench/grid-core/etc.)
  • Full repo pnpm typecheck clean

blove and others added 15 commits April 21, 2026 15:06
Three-surface editorial+terminal hybrid: playground (the pitch),
bench (the adversarial receipts), and a new apps/docs (Mintlify-
equivalent reference). Shared tokens, Fraunces + system stack,
amber accent, severity color as the only saturated grid signal.

Informed by competitor research on AG Grid, TanStack Table, MUI X
DataGrid, and Mintlify-layout patterns (Resend, Clerk, Stripe,
MUI X docs, Supabase docs).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Covers the shared design-system package: tokens CSS, Fraunces font wiring
via @fontsource-variable/fraunces, and five React components (Receipt,
Callout, CodeBlock, Nav, Footer). Does not migrate apps; that's Plans B-D.

Prettier formatting for both the plan and the spec.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add rootDir to tsconfig.typecheck.json so type-checking stays pinned to src/
- Resolve onSuccess CSS copies against the package dir via import.meta.url
  so tsup works whether invoked from the repo root or the package

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Without an afterEach(cleanup()) registration, React Testing Library does
not tear down the DOM between tests in vitest. Tests that scan the DOM
via queryByText (e.g. the 'renders children without requiring a tag'
case in callout.test.tsx) then see leftover elements from prior renders
and fail.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace the hardcoded #7d4f0a on .pt-callout-warn .pt-callout-tag with
a new --pt-amber-ink-dark token so the palette is fully centralized.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Give <Callout> role='note' so screen readers announce it as
supplementary information rather than a bare div.

Both variants use role='note'. role='alert' is for urgent,
time-sensitive content the user needs to act on immediately, which
doesn't fit a persistent docs callout even when styled as a warning.
Consumers who need urgent semantics can override with aria-live on
an ancestor.

Two new tests cover the default and warn cases.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The dot span carried aria-label="ci {status}" while the adjacent
visible text already reads "ci: {status}", so screen readers heard
"ci ci green green". Mark the dot aria-hidden — the visible text
carries the same information with correct phrasing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Address the final holistic review before merge:

- Tokenize two remaining hardcoded hex values in components.css
  (--pt-grid-head for code block head, --pt-ink-hover for nav CTA).
  Keeps the tokenization discipline consistent across the stylesheet.
- Move @fontsource-variable/fraunces from runtime dependency to
  optional peer dependency, matching the README: consumers import
  the font themselves, so the package should not pull it unconditionally.
- Add "sideEffects" field scoped to CSS so bundlers can tree-shake
  unused components from the JS barrel while preserving stylesheet imports.
- Add "./package.json" to the exports map for tooling (pnpm, publint).
- Use link.href as the React key in Footer links (label can collide).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@blove
Copy link
Copy Markdown
Contributor Author

blove commented Apr 21, 2026

Final review pass

Final holistic code review ran over the full package. Landed four in-scope polish items in 64afbbc:

  • Tokenized the last two hardcoded hex values (--pt-grid-head, --pt-ink-hover) so components.css contains zero hex literals.
  • @fontsource-variable/fraunces moved to optional peer dependency — package no longer pulls it unconditionally, matching the README guidance.
  • Added "sideEffects": ["**/*.css"] and ./package.json to the exports map (tree-shaking + publint hygiene).
  • Footer link key changed from label to href to avoid collisions.

Deferred (out of scope for this PR)

  • Nav's LINKS array is module-level / non-customizable → worth a follow-up when a second consumer needs different links.
  • CodeBlock copy button doesn't announce the "copied" state to screen readers → minor a11y refinement.
  • tsup.config.ts uses cp in onSuccess, not cross-platform → only matters if we ever support Windows development.
  • formatStars truncates at ≥1M → cosmetic.

CI status

test and format are failing on this branch. Both pre-exist on main — PR #6 was merged with the same two checks red. My branch only touches packages/ui/**; neither failure references those files:

  • format: apps/bench/src/query-state.ts (not touched here).
  • test: @pretable-internal/layout-core entry-resolution error from packages/grid-core (not touched here).

The three checks my package is responsible for are green: build, lint, typecheck.

blove and others added 3 commits April 21, 2026 17:46
The grid-core test script (vitest run) imports @pretable-internal/layout-core,
which resolves to ./dist/index.js via package.json exports. On fresh CI without
a pre-build step, dist/ does not exist and vitest errors with
"Failed to resolve entry for package".

packages/react already uses this alias pattern for @pretable-internal/renderer-dom
and @pretable/core. Apply the same approach here so grid-core tests can run
from a clean checkout.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
When the S4/S5 scenario branches were added to the parseBenchQuery nested
ternary, the indentation for S7 and its fallback drifted two spaces shallow.
Prettier's check flags this; prettier --write corrects the indent depth to
match the ternary nesting level.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@blove blove merged commit 3d8c57a into main Apr 22, 2026
5 checks passed
@blove blove deleted the claude/pedantic-joliot-7e6d20 branch April 22, 2026 00:50
blove added a commit that referenced this pull request May 11, 2026
…5 cross-validation

PR #128's S5/S7 cross-validation matrix surfaced a finding: AG Grid
Community matches pretable on every measured streaming numeric (frame
p95, 25k/sec envelope, visible-row drift). The homepage's stub-era
"purpose-built streaming pipeline" framing — and the implication that
pretable is uniquely fast at streaming — is no longer supportable on
hypothesis-scale numerics. The honest wedge is package surface:
pretable ships the SSE → partial-JSON → batcher → applyTransaction
pipeline as a single import; AG Grid expects you to wire it yourself.

Three editorial edits:

- ComparisonTable.tsx: streaming row renamed from "purpose-built
  streaming pipeline" to "streaming pipeline (SSE → partial JSON →
  batcher → applyTransaction)" — same yes/n/a/n/a/n/a shape, sharper
  capability claim. Header docblock updated to cite the S5/S7
  cross-validation milestone alongside the existing B2 sources.

- ReceiptsBand.tsx: replaced the "25k/s · max sustained update rate"
  hero stat (no longer pretable-unique) with "OpenAI · Anthropic · SSE
  · streaming sources, one import". Added a `compact: true` flag to
  the Stat interface so the longer label renders at 20–24 px instead
  of 44–56 px, preserving the four-cell grid without overflowing the
  hero font scale.

- FeatureGrid.tsx: Stream-aware card — dropped "sustained from 100 to
  25,000 updates/sec" tail; rewrote the description around the pipeline
  that ships as one import.

Test added: ReceiptsBand.test.tsx regression-guards the new capability
anchor (`streaming sources` + `openai`).

Repo-memory entry appended (B2 follow-up #7); MEMORY.md index updated;
project_b2_followups.md regenerated to reflect everything resolved
except item #5 (open comparator interaction scripts).

No source/package changes outside apps/website + the docs entry; all
190+ website tests pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
blove added a commit that referenced this pull request May 11, 2026
…5 cross-validation (#129)

PR #128's S5/S7 cross-validation matrix surfaced a finding: AG Grid
Community matches pretable on every measured streaming numeric (frame
p95, 25k/sec envelope, visible-row drift). The homepage's stub-era
"purpose-built streaming pipeline" framing — and the implication that
pretable is uniquely fast at streaming — is no longer supportable on
hypothesis-scale numerics. The honest wedge is package surface:
pretable ships the SSE → partial-JSON → batcher → applyTransaction
pipeline as a single import; AG Grid expects you to wire it yourself.

Three editorial edits:

- ComparisonTable.tsx: streaming row renamed from "purpose-built
  streaming pipeline" to "streaming pipeline (SSE → partial JSON →
  batcher → applyTransaction)" — same yes/n/a/n/a/n/a shape, sharper
  capability claim. Header docblock updated to cite the S5/S7
  cross-validation milestone alongside the existing B2 sources.

- ReceiptsBand.tsx: replaced the "25k/s · max sustained update rate"
  hero stat (no longer pretable-unique) with "OpenAI · Anthropic · SSE
  · streaming sources, one import". Added a `compact: true` flag to
  the Stat interface so the longer label renders at 20–24 px instead
  of 44–56 px, preserving the four-cell grid without overflowing the
  hero font scale.

- FeatureGrid.tsx: Stream-aware card — dropped "sustained from 100 to
  25,000 updates/sec" tail; rewrote the description around the pipeline
  that ships as one import.

Test added: ReceiptsBand.test.tsx regression-guards the new capability
anchor (`streaming sources` + `openai`).

Repo-memory entry appended (B2 follow-up #7); MEMORY.md index updated;
project_b2_followups.md regenerated to reflect everything resolved
except item #5 (open comparator interaction scripts).

No source/package changes outside apps/website + the docs entry; all
190+ website tests pass.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant