Skip to content

feat(emerald): add new paper design system#167

Draft
johnleider wants to merge 2 commits into
masterfrom
feat/emerald-paper-design-system
Draft

feat(emerald): add new paper design system#167
johnleider wants to merge 2 commits into
masterfrom
feat/emerald-paper-design-system

Conversation

@johnleider
Copy link
Copy Markdown
Member

Summary

  • Reworks Paper styling composables to output utility classes instead of inline CSS variables — cleaner, no runtime overhead, normal CSS specificity
  • Implements 3 reference Emerald components (EmButton, EmTextField, EmDialog) that establish the conventions for all future Paper DS component development
  • Adds Emerald design token definitions (colors, typography, borders, shadows) extracted from Juan's Figma spec
  • Adds .claude/rules/paper-components.md contract with 5 concrete patterns for building Paper DS components

Paper Composable Rework

All 6 composables (useBorder, useSpacing, useDimensions, useRounded, useElevation, useColor) now return utility class arrays. V0Paper applies via :class instead of :style.

Reference Components

Component Pattern Sub-components
EmButton Root with V0Paper Content, Prepend, Append, Loader
EmTextField Wrapping v0 compound (Input) Control, Label, Description, Error, Prepend, Append
EmDialog Renderless v0 root Content (V0Paper), Activator, Title, Description, Close

Design Tokens

Complete Emerald token system: primary (purple), secondary (slate), success/warning/error/info semantics, Manrope typography (6 sizes), border radius/width scales, 6 shadow elevations.

Test plan

  • pnpm typecheck — all 3 packages pass
  • pnpm lint:fix — clean
  • pnpm test:run — 88 files, 3921 tests passing
  • pnpm repo:check — knip + sherif clean
  • Manual review of reference component patterns
  • Verify token values match Juan's Figma spec (border radius/shadow values estimated)

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented Mar 26, 2026

Open in StackBlitz

commit: 7a69917

@johnleider johnleider marked this pull request as draft March 31, 2026 13:48
@johnleider johnleider force-pushed the feat/emerald-paper-design-system branch from db48422 to dce42a8 Compare April 28, 2026 16:02
Copy link
Copy Markdown
Contributor

@J-Sek J-Sek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have only focused about kitchen sink look&feel for now. Some small problems that should be easy to fix.

Other than mentioned in comments:

  • lack of animations (dialog, autocomplete menu, accordion, tabs)
  • carousel moves from slide 3 » 2 when clicked anywhere
  • any plans to support light/dark mode?

padding: 2px 10px 2px 6px;
font-size: 11px;
line-height: 18px;
letter-spacing: -0.02em;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO should be consistent with other variant. -0.02em is also a bit small for the chosen font face. rn looks like m, cl blends as well and might read as d.

<style>
.emerald-card__title {
margin: 0;
font-family: Manrope, system-ui, -apple-system, sans-serif;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be nice to have those styles driven from a handful of centralized CSS properties (font face, semantic colors, spacing, rounding). Otherwise consumption depends on availability of cheap AI tools that can handle tedious replacements.

border: 1px solid rgb(var(--emerald-neutral-channels) / 0.1);
border-radius: 8px;
overflow: hidden;
filter: blur(1px);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it looks like a bug with blur so small, especially when slides display text

:step
>
<template #default="slotProps">
<slot v-bind="slotProps" />
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For values near the edges (0-3 and 97-100) the thumb appears outside of the rounded track. The easiest fix that comes to mind would be just a div with padding around the thumb. Not sure if it can be done without introducing artificial EmSwitchThumbContainer. Ideally it would be solved on the lower level as it might be a typical scenario.

Comment on lines +79 to +84
.emerald-radio__indicator {
display: inline-flex;
align-items: center;
justify-content: center;
line-height: 0;
}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be removed, as it takes the size from the dot inside and gets centered by styles from the __box

>
<RadioIndicator class="emerald-radio__indicator">
<template #default>
<span class="emerald-radio__dot" />
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HTML-based radio button gets misaligned when using browser zoom. It might be better to have svg/icon here like in the checkbox.

Image

background: var(--emerald-primary-100);
border-left-color: var(--emerald-primary-500);
color: var(--emerald-primary-500);
font-weight: 500;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not look right and some popular typefaces change visual letter height between 400 and 500 weight - so this might be distracting. I'd just drop it to keep it safe.

@johnleider
Copy link
Copy Markdown
Member Author

Tried to update this PR to latest master but the conflict surface is too broad (273+ files: docs pages, examples, component test suites, philosophy doc, skill rules, multiple plugin adapters, etc.). The branch's last merge from master was at ff84a87a, and master has diverged significantly since. Suggest resolving locally with hand-merge or rebase given the scope of design feedback already applied. Left untouched.

Adds @paper/emerald — the first commercial design system built on the
Paper layer. Includes 36 component families (EmButton, EmTextField,
EmDialog, EmAutoComplete, EmAccordion, EmAvatar, EmBadge, EmBreadcrumb,
EmCard, EmCarousel, EmCheckbox, EmContainer, EmDatePicker, EmDivider,
EmFlex, EmForm, EmGrid, EmList, EmLoading, EmMenu, EmPagination,
EmProgress, EmRadio, EmSelect, EmSlider, EmStepper, EmSwitch, EmTable,
EmTabs, EmTag, EmTextarea, EmToast, EmTooltip, EmUpload), design tokens
from the Figma spec, an EmeraldStyleSheetAdapter that extends v0's
V0StyleSheetThemeAdapter, and a createEmeraldPlugin for one-line setup.

Also adds .claude/rules/paper-components.md — the path-scoped rule doc
that codifies the V0Paper-based component patterns design systems use.

Pulls in @phosphor-icons/vue via the pnpm catalog (used by Em components
for iconography) and registers packages/emerald in the knip workspace
config.
Adds the EmeraldKitchenSink page that renders every component family at
least once for visual verification. Registers a /emerald route in
dev/src/main.ts, exposes the emerald components directory and @paper/
emerald alias in dev/vite.config.ts, and lists @paper/emerald +
@phosphor-icons/vue as dev workspace deps.

Auto-imports (components.d.ts, composables.d.ts) regenerated to capture
the new Em* components and adapter exports surfaced by recent v0
changes.
@johnleider johnleider force-pushed the feat/emerald-paper-design-system branch from a1e4119 to 7a69917 Compare May 12, 2026 19:14
@johnleider
Copy link
Copy Markdown
Member Author

Force-pushed a clean reassembly of the emerald work on top of current master.

The previous branch had drifted ~6 months behind master and accumulated unrelated changes via a stale Merge origin/master commit. Bringing it forward would have meant resolving 273+ file conflicts spanning v0 composables, docs site, playground, and skill rules.

Instead, this is a fresh branch from master with only the emerald-scoped work pulled forward:

  • packages/emerald/ — full package (203 files, 36 component families, EmeraldStyleSheetAdapter, createEmeraldPlugin, design tokens)
  • .claude/rules/paper-components.md — Paper component contract
  • dev/src/EmeraldKitchenSink.vue + dev/main.ts route + dev/vite.config.ts components dir & alias
  • @phosphor-icons/vue added to the pnpm catalog
  • knip.json packages/emerald entry

Two commits:

  • feat(emerald): Paper design system foundation — Phase 0
  • chore(dev): wire Emerald kitchen sink at /emerald

Verified locally:

  • pnpm install clean
  • pnpm lint:fix — 1 auto-fix, 0 errors
  • pnpm typecheck — clean across packages/0, packages/paper, packages/emerald
  • pnpm dev + Playwright on /emerald — all 33 component sections render, 0 console errors/warnings

Original branch is preserved in the worktree at .claude/worktrees/paper-emerald if anything from the dropped commits needs to be revisited.

@johnleider johnleider changed the title feat(emerald): Paper design system foundation — Phase 0 feat(emerald): add new paper design system May 13, 2026
@johnleider johnleider self-assigned this May 13, 2026
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.

2 participants