feat(emerald): Paper design system foundation — Phase 0#167
Draft
johnleider wants to merge 17 commits intomasterfrom
Draft
feat(emerald): Paper design system foundation — Phase 0#167johnleider wants to merge 17 commits intomasterfrom
johnleider wants to merge 17 commits intomasterfrom
Conversation
…t stubs New package at packages/emerald/ with Em-prefixed component stubs (EmButton, EmCard, EmDialog, etc.) extending V0Paper for styling primitives. Divider, Flex, and Grid use bare Atom.
Defines the must/may/must-not contract for Paper design system components and the build pipeline (spec → implement → review). Key decisions: props → utility classes for styling, data attributes for state, named slots become components, explicit v-model re-exposure.
Paper composables now return class string arrays instead of CSS variable style objects. V0Paper applies via :class instead of :style. SCSS simplified to base reset — utility classes handle all styling. Color utility functions (hexToRgba, etc.) extracted to color-utils.ts and re-exported for consumers who need runtime color parsing.
First reference component establishing Paper DS conventions: - Root with V0Paper, sub-components as plain elements - Props forwarded to V0Paper via v-bind spread - Data attributes for state styling (disabled, loading) - Explicit event re-exposure, no $attrs forwarding - Sub-components: EmButtonContent, EmButtonPrepend, EmButtonAppend, EmButtonLoader
Second reference component. Demonstrates: - Wrapping v0 compound component (Input.Root + sub-components) - V0Paper on root, raw v0 primitives on Control/Description/Error - DS-specific sub-components (Label, Prepend, Append) - Explicit v-model re-exposure for input value - Form validation integration via Input.Root props
Third reference component. Demonstrates: - Wrapping v0 behavioral compound component (Dialog) - Root is renderless — no V0Paper wrapper needed - EmDialogContent gets V0Paper for independent styling (elevation, rounded, background on the dialog panel) - Explicit v-model for open/close state - Event re-exposure (cancel, close)
Contract now includes 5 concrete patterns with real code from the reference components. Removed Phase 0 TODOs — composable rework is done (utility classes, not inline styles). Added patterns for: renderless v0 roots, sub-component wrapping, slot prop forwarding, naming conventions, and styling guidelines.
Defines the complete Emerald token system extracted from Juan's Figma: - Brand: primary (purple #7C5CF6), secondary (slate #94A3B8) - Semantics: success, warning, error, info with 11-step luminosity - Surfaces: background (#FAF9FF), surface (#F5F4FF) - Border: radius scale (8 steps), width scale (6 steps) - Shadows: 6 elevation levels - Typography: Manrope, 6 sizes (xs-2xl) with weights/line-heights - Icons: Phosphor Icons (Regular)
No longer imported after composable rework — composables no longer need component names for CSS variable scoping.
|
commit: |
Orchestrates v0 plugin installation with Emerald defaults:
- Theme with Emerald color palette
- Locale (default: en)
- Logger, Storage, Hydration
All plugins installed by default with Emerald defaults.
User options override, set to false to disable.
Usage:
app.use(createEmeraldPlugin())
app.use(createEmeraldPlugin({ theme: { default: 'dark' } }))
app.use(createEmeraldPlugin({ locale: false }))
Batteries-included documentation DS with 34 component stubs: Shell: AppBar, AppNav, AppMain, AppFooter, AppBanner Navigation: NavLink, Breadcrumbs, PageNavigator Content: CodeBlock, Callout, ApiTable, ApiCard, Toc, Example, ExampleCode, Faq, FaqItem, HeaderAnchor, Card, Mermaid Interactive: Search, CopyCommand, BackToTop Utility: Icon, IconButton, Link, Divider, Switch, Chip, CloseButton, Kbd, Skeleton, LoaderIcon, ProgressBar Includes token system (colors, z-index, easing, durations, shadows, typography, border-radius) and createCodexPlugin for one-line setup with v0 sub-plugins.
Ported from docs site with Paper DS conventions: Content: - CxCallout (tip/info/warning/error with config) - CxHeaderAnchor (heading with anchor link) - CxCard (hoverable, linkable, disableable) - CxFaq + CxFaqItem (accordion FAQ via v0 ExpansionPanel) - CxCopyCommand (command pill with clipboard copy) - CxCodeBlock stub (pending Shiki integration) Indicators: - CxProgressBar (ARIA progressbar with fill animation) - CxSkeleton (loading placeholder with pulse animation) - CxLoaderIcon (spinner/dots/wave/orbit variants) - CxBackToTop (scroll-aware visibility via v0 event listeners) Utility: - CxKbd (keyboard shortcut styling) Composable: - useClipboard (clipboard API wrapper with auto-reset)
Utility: CxDivider, CxChip, CxCloseButton, CxLink, CxSwitch Icons: CxIcon (slot-based), CxIconButton (V0Paper button) Navigation: CxBreadcrumbs (v0 Breadcrumbs), CxPageNavigator (prev/next) All stripped of docs-specific coupling. CxBreadcrumbs accepts generic items array, CxPageNavigator accepts prev/next link objects. CxLink auto-detects external URLs. CxSwitch wraps v0 Switch compound.
App Shell: - CxAppBar (fixed header), CxAppNav (sidebar with mobile toggle), CxAppMain (responsive content area), CxAppFooter (inset-aware), CxAppBanner (top announcement bar) Navigation: - CxNavLink (tree item with expand/collapse, depth indentation) Documentation Content: - CxToc (table of contents with active state) - CxCodeBlock (code display with copy, line numbers, Shiki slot) - CxExampleCode (peek/expand code pane with fade gradient) - CxExample (preview + code container) - CxApiTable (prop/event/slot reference table) - CxApiCard (individual API item card) - CxSearch (dialog shell wrapping v0 Dialog) - CxMermaid (diagram container with figcaption) All 34 codex components now implemented. All stripped of docs-specific coupling — generic, composable containers.
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
1 participant
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.
Summary
.claude/rules/paper-components.mdcontract with 5 concrete patterns for building Paper DS componentsPaper Composable Rework
All 6 composables (
useBorder,useSpacing,useDimensions,useRounded,useElevation,useColor) now return utility class arrays. V0Paper applies via:classinstead of:style.Reference Components
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 passpnpm lint:fix— cleanpnpm test:run— 88 files, 3921 tests passingpnpm repo:check— knip + sherif clean