` — use ``. - ❌ Inventing `` or any name outside the 9-step ramp. Scale: `caption · body-sm · body · body-lg · title-sm · title · title-lg · display · display-lg`. - ❌ `line-height: 1.55;` literal in CSS Modules. Always `var(--v-leading-relaxed)` (or `tight`/`snug`/`normal`). - ❌ `letter-spacing: -0.02em;` literal. Always `var(--v-tracking-tight)` (or `normal`/`wide`/`eyebrow`). - ❌ `font-weight: 500;` in CSS Modules. Always `var(--v-font-weight-medium)`. - ❌ `` numeric. Numeric escape hatch was removed in 0.1.0 — pick the semantic name. --- ## Spacing rhythm ### The ladder Think in steps. Each "level" of grouping uses a value 1–2 steps higher than the previous: | Step | Token | Use | |---|---|---| | Inline | `--v-{height,width}-2` to `-8` | Internal component spacing, icon gap, label-to-input | | Tight | `--v-height-12` | eyebrow → title | | Standard inline | `--v-height-16` | row gaps, default gap inside a card | | Group | `--v-height-24` | badge → title group, tier feature list | | Major group | `--v-height-32` | title group → actions | | Section internal | `--v-height-48` to `-64` | header → grid, intro → content | | Section padding compact | `--v-height-96` | logoCloud, footer, mobile sections | | Section padding standard | `--v-height-128` | hero, feature, pricing | **Rule:** never mix two adjacent steps in the same axis without intent. If a value you need isn't in the scale (e.g. 30px), **pick the nearest token (28 or 32)** — almost certainly the design wants the rhythm, not the literal. ### Section vertical rhythm — the canonical block template Every section block follows this pattern. Mirror it when composing custom sections: ``` section padding-top : --v-height-128 (hero/feature) or --v-height-96 (compact) header → content gap : --v-height-48 to --v-height-64 title → subtitle gap : --v-height-12 title group → actions : --v-height-32 section padding-bottom : same as top ``` Mobile (`@media (max-width: 768px)`): drop padding to `--v-height-96`, shrink display titles to ~32–40px via `font-size: Npx !important` (only legitimate `!important` use — overrides `Text`'s inline `--font-size`). ### `--v-page-padding` is the outer gutter Use `--v-page-padding` for the outermost horizontal padding of any section. Never substitute a numeric token (`--v-width-16`) for the page gutter — apps may override the page gutter to a different rhythm. ### Proportion — equalize with tokens and layout, not with measured pixels Mismatched widths, uneven columns, and controls of subtly different heights are the most common "it looks off" bugs. They are **deterministic to fix** — never reach for a dev server to measure the gap and hand-tune a px value. - **Equal-weight siblings get equal tracks.** Columns/cards meant to align should be a CSS grid (`grid-template-columns: repeat(N, 1fr)`) or `flex: 1` items — the layout equalizes them at any viewport. If they must be a fixed size, both pull the **same** `--v-width-N`. Two different hand-picked widths is the bug. - **One `size` prop per control row.** Inputs, buttons, selects, and badges in the same group all take the same `size` (`sm`/`md`/`lg`). Their heights, paddings, and fonts then derive from the same `--v-{field,…}-{size}-*` composites and align automatically. Never size one control with raw tokens while its neighbor uses a `size` prop. - **A width mismatch is a cause, not a measurement.** It's almost always (a) an off-scale literal, (b) two siblings on different tokens, or (c) asymmetric padding / `box-sizing`. Diagnose the cause and snap both sides to one token — don't sample rendered frames and nudge. - **Proportional whitespace follows the ladder.** Gaps between paired elements scale with their grouping level (above), not with the elements' own size. Don't widen a gap "to balance" a larger heading — bump it one ladder step or leave it. - **Aspect ratio for media, not magic heights.** Image/illustration/video wells use `aspectRatio` (the `@vireya/ui/layout/aspectRatio` component or the CSS prop with a clean ratio like `16/9`), so they scale with their column instead of fighting it with a fixed px height. --- ## Radius hierarchy — children smaller than parent Rounded shapes should **increase with element size**, and **inner elements take a smaller radius than their container**: | Element | Token | |---|---| | Hairline (chart inner element) | `--v-radius-xs` | | Sharp (chart bar, micro indicator) | `--v-radius-xs` | | Inline (badge, chip, tag, tooltip) | `--v-radius-sm` | | Small (input, alert, dropdown menu) | `--v-radius-md` | | Medium (button `shape_square`) | `--v-radius-lg` | | Large (card, feature item, dialog) | `--v-radius-xl` | | X-large (pricing tier, hero card, drawer) | `--v-radius-2xl` | | Pill / circle | `--v-radius-full` (= 9999px) or `50%` for circle | **Rule:** children take a smaller radius than the parent. A button (`--v-radius-lg`) inside a card (`--v-radius-xl`) — never the inverse. Step down the scale: `2xl → xl → lg → md → sm → xs`. **Anti-patterns:** - ❌ `--v-radius-sm` on a 200px-tall card (looks sharp/cheap) - ❌ `--v-radius-2xl` on a 24px badge (looks like a balloon) - ❌ `9999px` on anything that isn't a true pill (avatar, status dot, single-line tag) --- ## Elevation — Vireya is low-elevation We prefer **borders + subtle background tint over shadows**. Shadows appear only on: 1. Hover lifts (cards, tier cards) — soft, short-throw 2. Floating layers (popover, dropdown, tooltip, modal) — defined, more spread | Layer | box-shadow | |---|---| | Resting (card at rest) | **none** — use `border: 1px solid var(--v-secondary-border)` instead | | Hover lift | `0 8px 24px -12px rgba(0, 0, 0, 0.08)` | | Pricing/featured hover | `0 12px 32px -16px rgba(0, 0, 0, 0.10)` | | Popover / dropdown | `0 8px 24px -8px rgba(0, 0, 0, 0.12)` | | Modal / drawer | `0 24px 48px -16px rgba(0, 0, 0, 0.20)` | **Forbidden:** - ❌ Multi-layer shadows (`box-shadow: 0 1px 2px ..., 0 4px 8px ...`) - ❌ Warm tints (`rgba(20, 10, 0, 0.1)`) — shadows are pure black + low alpha - ❌ Resting shadow on non-floating surfaces — depth comes from border + tone (These are inline today; tokenizing as `--v-elevation-{rest,hover,popover,modal}` is a tracked gap.) --- ## Motion — animate state changes, not vibes ### Budget | Role | Duration | |---|---| | Instant | `0ms` — focus ring (immediate, communication) | | Fast | `150ms` — micro-interactions (hover color, focus ring fade) | | Default | `var(--v-motion-duration)` (250ms) — state transitions, accordion expand | | Slow | `400ms` — drawer slide, page-level reveal | | Slower | `600ms` — orchestrated, sequenced reveals | ### Easing Default `var(--v-motion-timing)` (`cubic-bezier(0.4, 0, 0.2, 1)`, material standard) covers ~95% of cases. When you need: - **Enter** (decelerating in): `cubic-bezier(0, 0, 0.2, 1)` (ease-out) - **Exit** (accelerating out): `cubic-bezier(0.4, 0, 1, 1)` (ease-in) - **Emphasized/playful**: `cubic-bezier(0.68, -0.55, 0.27, 1.55)` (overshoot) **Linear easing is wrong for everything except progress bars and loading shimmer.** ### What to animate, what NOT to - ✅ State changes that change layout (open/close, expand/collapse) - ✅ Hover color shifts (≤ default duration) - ✅ Focus ring fade-in - ❌ Hover transform lifts on touch (use `@media (hover: hover) and (pointer: fine)` to gate) - ❌ `transition: all` (always name properties) - ❌ Mandatory entrance animations with no reduced-motion fallback ### Reduced motion is mandatory Always wrap meaningful animation: ```css @media (prefers-reduced-motion: reduce) { .myAnim { animation: none; transition: none; } } ``` Hover color shifts and focus rings are **exempt** — they're communication, not motion. --- ## States — every interactive component must distinguish all of these | State | Trigger | Visual | |---|---|---| | Default | At rest | Base color, base border | | Hover | `:hover` (pointer only — gate with `@media (hover: hover)` for transforms) | `var(--v-{name}-hover)` bg or border lift | | Active / Pressed | `:active` | `var(--v-{name}-active)` or compress (transform ≤ 1px) | | Focus-visible | `:focus-visible` (NEVER `:focus` alone) | `outline: 2px solid var(--v-primary-fill); outline-offset: 2px;` | | Disabled | `:disabled` / `[aria-disabled="true"]` | `opacity: 0.5; cursor: not-allowed;` no hover response | | Loading | `data-loading` / prop | Hide content (`visibility: hidden`), absolutely-positioned loader centered | | Selected / Checked | `[aria-selected]`, `[data-state="checked"]` | Fill with `--v-primary-fill`, border with `--v-primary-fill` | | Invalid | `aria-invalid="true"` | Border `var(--v-destructive-fill)`, helper text destructive | **Focus rule:** `:focus` alone fires on mouse clicks too — wrong default. Always `:focus-visible`. Never `outline: none` without a replacement. **Hover rule on touch:** color shifts are OK on touch (read as tap feedback). Transform lifts are NOT — they tap-flicker. Gate transforms with `@media (hover: hover) and (pointer: fine)`. --- ## Responsive — one canonical breakpoint Vireya uses **`768px`** as the primary breakpoint. Below = mobile, above = desktop. Tablet is "small desktop" unless content explicitly demands otherwise. Secondary breakpoints used **sparingly** when a multi-column grid demands a middle tier: - `1024px` — drop 4-col → 2-col - `640px` — drop 2-col → 1-col **Forbidden:** - ❌ Per-component arbitrary breakpoints (`@media (max-width: 819px)`). Pick one of the three. - ❌ Mobile-first `min-width` queries in marketing/landing code (we write desktop-first). ### Touch vs hover gating Use `@media (hover: hover) and (pointer: fine)` to gate hover-only effects (transform lifts, parallax). On touch, those become tap-flickers. ### Charts adapt to their container, not the viewport Charts can sit in narrow columns (sidebar, 2-up grid, dashboard tile). They use `useChartBreakpoint()` from `@vireya/ui/data/chart` and write `data-chart-bp="xs|sm|md"` on the root. CSS reacts via attribute selectors, not viewport queries. --- ## Visual depth — gradients, spotlights, masks Vireya's signature look isn't shadows — it's **soft radial spotlights on top of solid token surfaces**. The treatment is restrained, token-driven, and built from a small set of recipes you compose. Six patterns cover what the official Vireya marketing site uses. ### Universal rules — apply to every gradient 1. **Translucent stops use `color-mix(in srgb, X N%, transparent)` — never `rgba()`.** Tokens have no alpha channel; `color-mix` is the alpha mechanism that stays inside the token system. Banned: `rgba(0,0,0,0.4)`. Required: `color-mix(in srgb, var(--v-primary-fill) 40%, transparent)`. 2. **Always layer the gradient over a solid `var(--v-background-fill)` (or `secondary-fill`)**, never let the gradient be the sole background. If the radial fails to render or the user has a forced theme, you still get a clean surface underneath. 3. **End every spotlight stop at `transparent`** — never end at a solid color. Sharp edges read as bugs. 4. **All colors are tokens.** No `#fff`, no `hsl(...)` literals. Spotlights use `--v-secondary-fill` as the "warm tint"; accent glows use `var(--v-accent-fill, var(--v-primary-fill))` or a scoped `--v-accent-example-*`. 5. **Geometry is proportional (%), not pixel.** Spotlights resize fluidly with the container — no mobile breakpoint needed for the gradient itself. ### Pattern A — Top-spotlight hero (THE Vireya signature) The single most recognizable Vireya treatment. Used on every page hero and showcase header. "Light bleeds from the top centerline." ```css .hero { width: 100%; background: radial-gradient( ellipse 60% 50% at 50% 0%, var(--v-secondary-fill) 0%, transparent 70% ), var(--v-background-fill); border-bottom: 1px solid var(--v-secondary-border); } ``` **Geometry to memorize:** `ellipse 60% 50% at 50% 0%` — 60% wide, 50% tall, centered horizontally, anchored to the top edge. Stop fades from `secondary-fill` to `transparent` at 70%. **Bottom-cap is part of the look.** The `border-bottom: 1px solid var(--v-secondary-border)` is what makes the hero feel anchored. Don't drop it. ### Pattern B — Bottom-spotlight card visual Inverse of A — used inside cards where an illustration sits at the bottom and you want it to "rise from light". A common use is templates card visuals. ```css .cardVisual { background: radial-gradient( ellipse 60% 80% at 50% 100%, var(--v-secondary-fill) 0%, transparent 70% ), var(--v-background-fill); width: 100%; height: 100%; } ``` **Geometry:** `ellipse 60% 80% at 50% 100%` — same width as A, taller (80%), anchored to bottom-center. Pair with Pattern D (bottom-fade mask on the illustration itself) for the canonical "illustration melting into card" effect. ### Pattern C — Accent glow overlay (per-card branded glow) Two-layer composite that paints an accent halo at the top of a card and fades the bottom into the page. Common use: real-world-examples sections that need brand color over neutral screenshots. ```css .glow { position: absolute; inset: 0; z-index: 1; pointer-events: none; background: /* Top: accent halo */ radial-gradient( ellipse 90% 70% at 50% 0%, color-mix(in srgb, var(--v-accent-fill, var(--v-primary-fill)) 30%, transparent) 0%, transparent 60% ), /* Bottom: fade into page bg, helps text legibility */ linear-gradient( to bottom, transparent 55%, color-mix(in srgb, var(--v-background-fill) 65%, transparent) 100% ); } ``` **Rules:** - `pointer-events: none` is mandatory — the glow is decoration, not a click target. - Absolute `inset: 0` + a parent with `position: relative; isolation: isolate` (so `z-index` stacking is local). - The accent stop tops out at **30% opacity** — anything more saturates and reads cheap. - The bottom linear-gradient is what makes white text on the glow stay readable. - Per-instance accent: scope a CSS custom property on a wrapper (`

` defines `--v-accent-example-fill: hsl(...)`), and the glow reads it via `var(--v-accent-example-fill, var(--v-accent-fill, var(--v-primary-fill)))`. **Never set a literal color on the glow itself.** ### Pattern D — Bottom-fade mask (illustration → card edge) Makes an SVG illustration dissolve into the bottom of its container. The mask is purely geometric — no color tokens involved. ```css .illustration { mask-image: linear-gradient(to top, transparent 0%, black 35%); -webkit-mask-image: linear-gradient(to top, transparent 0%, black 35%); } ``` **Geometry:** the bottom **35%** of the element fades to transparent. The number is calibrated — at 25% the illustration looks abruptly cropped; at 50% it loses the focal point. **Always include the `-webkit-mask-image` line** for Safari. The two declarations always come together. Pair with a hover lift to make the illustration feel alive: ```css .card:hover .illustration { transform: translateY(calc(var(--v-height-4) * -1)); } ``` ### Pattern E — Translucent overlay surface (frosted-glass UI) Floating UI element layered over a busy background (screenshot, illustration, gradient). Combines a translucent fill, backdrop blur, and a translucent border. ```css .overlay { background: color-mix(in srgb, var(--v-background-fill) 70%, transparent); backdrop-filter: blur(var(--v-width-8)); -webkit-backdrop-filter: blur(var(--v-width-8)); border: 1px solid color-mix(in srgb, var(--v-secondary-border) 60%, transparent); border-radius: var(--v-radius-lg); padding: var(--v-height-4); } ``` **Recipe:** - Background: 70% of the page fill, 30% transparent — lets the underlying content tint through. - Border: 60% of the standard border token, 40% transparent — keeps the edge visible without going hard. - Blur: `var(--v-width-8)` (16px) is the calibrated default for "noticeable but not smeary". - Always include the `-webkit-backdrop-filter` prefix. ### Pattern F — Halo text-shadow (legibility on busy bg) When text sits over a screenshot, illustration, or any non-uniform background, add a tiny halo built from the page bg color. Reads as legibility aid, not as decorative shadow. ```css .textOverImage { text-shadow: 0 1px 2px color-mix(in srgb, var(--v-background-fill) 80%, transparent); } ``` **Rules:** offset `0 1px`, blur `2px`, color built from `--v-background-fill` at 80%. **Never** use a black shadow over light text — it reads as drop-shadow drama instead of a halo. ### Composition — what makes a Vireya page "feel like Vireya" Stack these three pieces and you've got the canonical look: 1. **Hero with Pattern A** (top-spotlight + bottom-cap border). 2. **Sections with `Section.Root`** (no gradient — solid `--v-background-fill` with the section header underline). 3. **Cards with Pattern B inside the visual area** + Pattern D mask on illustrations + Pattern E for any floating chip/palette/badge over media. The rhythm is: **gradient at the top of the page, neutral middle, gradient inside cards.** Don't gradient every section — the top-spotlight is a punctuation mark, not body type. ### Anti-patterns | Smell | Fix | |---|---| | `background: rgba(0,0,0,0.4)` | `background: color-mix(in srgb, var(--v-primary-fill) 40%, transparent)` | | `background: linear-gradient(...)` with no solid fallback | Layer the gradient OVER `var(--v-background-fill)` | | Spotlight ending at a solid color stop | End every spotlight at `transparent` | | Gradients on every section | Spotlights are punctuation — hero + cards only | | Accent glow at >40% opacity | Cap at 30% — anything more saturates | | Hardcoded `#fff` text-shadow | `color-mix(in srgb, var(--v-background-fill) 80%, transparent)` | | Missing `-webkit-mask-image` / `-webkit-backdrop-filter` | Always pair the prefixed version with the standard one | | Per-card accent set as a literal | Scope it as a CSS custom property on a wrapper class, read via `var(...)` chain | --- ## Composition decisions ### Slots beat configuration when the contained content varies ```tsx // WRONG — closed configuration explodes // RIGHT — open slot New} /> ``` ### `asChild` for polymorphism — never `href` on every component ```tsx // RIGHT // WRONG — forces Button to know about routing ``` ### Compound API rule — simple stays as prop, JSX-rich becomes a child For multi-part components, expose a namespace (``, ``, …). Split rule: > **Simple values stay as props on `Root` (text, enums, booleans, numbers). Interactive or JSX-rich content goes through children + named sub-components.** ```tsx // WRONG — opaque slot props, no IDE structure, forces Fragment ``` Sub-components are identified by `displayName = "FamilyVariant.PartName"` and filtered with `findChild`/`findChildren`/`excludeChildren` (no Context overhead for slot extraction). Use `createContext` only when sub-components share runtime state (e.g. `CTAInlineEmail.Form`'s email input + submit button). ### Compound vs flat — never expose both for the same concern If `Dialog` already exposes `Dialog.Root + .Trigger + .Content + .Header + .Footer`, don't also ship a ``. Pick one API per concern. ### Forward refs and rest props — always `forwardRef + ...props` spread is the contract Vireya follows. When you write your own components, do the same: never filter unknown props — consumers (you, future-self, teammates) add `aria-*`, `data-*`, event handlers you don't know about. --- ## CTA decision matrix — Button variant × surface × size | Role | `variant` | `surface` | `size` | Notes | |---|---|---|---|---| | Hero primary | `accent` (or `primary` if no accent in theme) | `solid` | `lg` | The single highest-emphasis CTA on the page | | Hero secondary | `secondary` | `outlined` | `lg` | Sits next to hero primary, lower emphasis | | Section primary | `primary` | `solid` | `md` | Default in-page CTA inside a section | | Section secondary | `secondary` | `outlined` or `ghosted` | `md` | Adjacent to a primary, or a quiet standalone action | | Card action | `secondary` | `ghosted` | `sm` | Card hover-revealed CTA, "Learn more →" | | Destructive | `destructive` | `solid` | `md` | Pair with `AlertDialog` for confirmation | | Toolbar / table row | `secondary` | `ghosted` | `sm` or `ss` | Dense surfaces — icon + label or icon-only | **Rules:** - **Never two `solid` buttons of the same `variant` in the same group.** One leads (solid), the other demotes to `outlined` or `ghosted`. Two equally-loud CTAs = no CTA. - **Wrap router links via `asChild + ` — never invent an `href` prop on Button.** - **For accent-driven branded moments**, prefer `variant="accent"` over `variant="primary"`. Reserve `primary` solid for the neutral-strong default. --- ## Emphasis decision rule — `accent` or `primary` on blocks The 8 blocks that expose `emphasis: "primary" | "accent"`: `hero/{centered, splitVisual}`, `pricing/{tiers, twoTier}`, `feature/{steps, checkList, highlights}`, `eyebrow`. Default is `"accent"`. **Default to `accent`** for hero, pricing, and feature highlights — promotional surfaces that anchor the page. **Switch to `primary`** when: - The page has no defined accent in the theme (renders identical to primary, but the explicit choice signals intent). - The section is legal/footer/utility chrome that shouldn't draw promotional attention. - You've already used accent in the same viewport-fold. **Rule of thumb: one accent moment per fold.** Two accent CTAs above the fold dilute the brand color. The other 19 blocks intentionally lack `emphasis` because they have no internal element where the choice would have a visible effect (footers/navbars/logo clouds are neutral chrome; CTAs use `variant`). Drive accent there via the `eyebrow` slot — pass `Featured` directly when you need accent. --- ## Self-audit checklist — run before declaring a page done If any check fails, the page is not done. - [ ] **Tokens only**: `grep -RE '#[0-9a-fA-F]{3,8}\b|rgba?\(|\b\d+px\b' src/**/*.module.css` returns nothing inside your section CSS (allowed: `0`, `100%`, `9999px`, `1px`/`1.4px` in inline SVG). - [ ] **Dark theme survives**: toggle to dark theme — no text becomes invisible, no accent CTA disappears (means every accent reference has a `var(--v-accent-*, var(--v-primary-*))` fallback chain). - [ ] **Focus-visible everywhere**: tab through the page — every interactive element shows a visible 2px outline. - [ ] **Server-renderable**: hero, sections, footer all render their content without JS (interactivity may be inert; content must show). - [ ] **Mobile (640px wide)**: section titles shrink (`var(--v-font-size-title) !important`); section padding shrinks to `--v-height-32`; no horizontal scroll. - [ ] **No twin-`solid` CTAs**: in any group, at most one button is `solid` of the lead variant; siblings demote to `outlined` / `ghosted`. - [ ] **No nested blocks**: `@vireya/blocks` blocks never contain other blocks. Sub-sections compose `@vireya/ui` primitives inside `Section.Root`. - [ ] **``** is set in `app/layout.tsx`. - [ ] **`AppProvider` wired** with the full 14-icon map and a locale. - [ ] **No barrel imports**: every `@vireya/ui` and `@vireya/blocks` import is a subpath (the ONE exception is `import { AppProvider } from "@vireya/ui"`). - [ ] **Section.Title pairing**: section titles are `size="title-lg" weight="semibold"`, paired with `` descriptions. - [ ] **One accent moment per viewport-fold**. If two folds both have an accent CTA, demote one to `primary`. --- ## Component pairing — which to pick ### Modal / overlay taxonomy | Component | Use for | |---|---| | `Dialog` | **Blocking decisions** — confirmations, forms that need full attention. Modal backdrop. | | `AlertDialog` | **Destructive confirmations only** — "Delete project?". `Action`/`Cancel` buttons mandatory. | | `Sheet` | **Contextual side panels** — settings, filters, details. Doesn't fully break the flow. | | `Drawer` | **Mobile-style bottom slide-up** — share sheets, filters on touch. (Built on Vaul.) | | `Popover` | **Inline disclosure ≤300px** — color picker, quick form, contextual actions. Anchored to trigger. | | `HoverCard` | **Preview on hover ≤1 sentence** — user mention preview, link metadata. Never actionable content. | | `Tooltip` | **≤1 sentence on hover only** — clarification, keyboard hint. Never actionable, never essential info. | | `DropdownMenu` | **List of actions/links** — context menu, "more" menu. Items are commands. | | `ContextMenu` | **Right-click menu** — same as dropdown but trigger is `contextmenu` event. | | `Toast` | **Async feedback ≤3 lines** — "Saved", "Connection lost". Auto-dismisses. Non-blocking. | **Rules:** - Anything actionable → `Popover` (anchored) or `DropdownMenu` (list of actions). NEVER `Tooltip` or `HoverCard`. - Confirmations destructive → `AlertDialog`. Confirmations non-destructive → `Dialog`. - Filter/settings on desktop → `Sheet`. Same on mobile → `Drawer`. ### Page section taxonomy — `@vireya/blocks` are FULL sections | Layer | Role | |---|---| | `@vireya/blocks` | Full landing-page sections (Hero, Pricing, FAQ, Footer). One per page-region. | | `@vireya/ui` | Primitives (Button, Card, Input, Tab). Compose into custom sections when no block fits. | **Rules:** - Never nest a block inside another block. If a feature section needs a sub-section, compose `@vireya/ui` primitives directly. - Never re-implement a block as primitives if the block exists. `Hero.Centered` already handles eyebrow + title + description + actions + responsive — don't rebuild it. - Always pass `eyebrow` as a `ReactNode` slot (use the `Eyebrow` primitive, not a custom span). Block props like `eyebrow?: ReactNode` accept rich nodes. ### `emphasis` prop — defaults to `accent` Blocks with an `emphasis: "primary" | "accent"` prop default to `"accent"`. Change to `"primary"` only when: - The eyebrow text **is** a CTA label (rare) - The page has no defined accent and you want to be explicit - A neutral/legal/footer section that shouldn't draw promotional attention --- ## Block-scoped tokens `@vireya/blocks` follows a **two-layer token model**: blocks consume design system tokens (`--v-*`), but expose their own scoped surface (`--v-block-{family}-{property}`) for per-block customization. ### When to add a block-scoped token Tokenize **identity-defining** properties — values where a brand or consumer would reasonably want to differ: - ✅ Surface colors (card bg, section bg) - ✅ Border colors - ✅ Accent colors (highlights, indicators) - ✅ Decorative properties unique to the block (overlay color, grayscale opacity) - ❌ Spacing, padding (use design system tokens directly) - ❌ Layout properties (grid, flex) - ❌ Typography weight/size (already tokenized globally) ### Defaults must be design system tokens ```css .section { /* RIGHT — falls back to active theme out of the box */ --v-block-hero-accent: var(--v-primary-fill); /* WRONG — locks the block to a literal */ --v-block-hero-accent: #00aa55; } ``` Override at any cascade level: per-instance via `style`, per-page via wrapper class, per-theme via `:root.v-theme-brand body { ... }`. --- ## Accessibility floors These are minimums. Going below is a bug. - **Color contrast:** WCAG AA (4.5:1 body, 3:1 large text). Default themes meet this; verify custom themes before shipping. - **Focus indicators:** every interactive element needs a visible `:focus-visible` ring. - **Keyboard:** every interactive element reachable + operable via keyboard. No mouse-only handlers. - **Hit targets:** primary CTAs ≥ 44×44px (use `lg`/`xl` field size). Inline icon buttons may go ≥ 32px in dense contexts. - **ARIA:** primitives from `@base-ui-components/react` and Radix come with correct ARIA — don't strip it. Propagate `aria-*` props explicitly. - **Semantic HTML:** `` | | ` ``` **Rules:** - Never two `variant="primary"` buttons. Promote one (the actual decision), demote the other to `secondary` + `surface="outlined"` or `surface="ghosted"`. - For accent-driven CTAs (promotional / branded moments), use `variant="accent"` instead of primary. - Always wrap router links via `asChild + ` — never invent an `href` prop on Button. --- ## 5. Pricing tier with a custom CTA per tier ```tsx "use client"; import { PricingTiers } from "@vireya/blocks/pricing/tiers"; import { Button } from "@vireya/ui/form/button"; import Link from "next/link"; Core features Community support Everything in Starter Priority support ``` **Notes:** - Anything that isn't a `PricingTiers.Feature` becomes the tier's **action slot** — typically your CTA button. - The highlighted tier auto-receives Root's `emphasis` (defaults to `accent`); pass `emphasis="primary"` on Root to mute the brand color. - Use `highlighted` + `highlightedLabel` (NOT `popular`). --- ## 6. Install snippet — package-manager tabs + Shiki-rendered code The install snippet section is server-side syntax-highlighted with Shiki, with a tiny client component for the copy interaction. ```ts // app/lib/highlight.ts (or similar — server-only) import { codeToHtml } from "shiki"; const cache = new Map>(); export function highlightTsx(source: string) { const cached = cache.get(source); if (cached) return cached; const promise = codeToHtml(source, { lang: "tsx", themes: { light: "github-light", dark: "github-dark" }, defaultColor: false, }); cache.set(source, promise); return promise; } ``` ```tsx // app/components/install.tsx (server async) import { TabsRoot, TabsList, TabsTrigger, TabsContent } from "@vireya/ui/data/tab"; import { highlightTsx } from "../lib/highlight"; import { CopyButton } from "./copy-button"; export const InstallSection = async () => { const html = await highlightTsx(`import { Button } from "@vireya/ui/form/button";\nexport default () => ;`); const commands = [ { id: "pnpm", label: "pnpm", command: "pnpm add @vireya/ui" }, { id: "npm", label: "npm", command: "npm install @vireya/ui" }, { id: "yarn", label: "yarn", command: "yarn add @vireya/ui" }, ]; return ( {commands.map((c) => {c.label})} {commands.map((c) => ( $ {c.command} ))}

); }; ``` ```tsx // app/components/copy-button.tsx "use client"; import { useState } from "react"; import { Check, Copy } from "lucide-react"; export const CopyButton = ({ value }: { value: string }) => { const [copied, setCopied] = useState(false); return ( ); }; ``` **Why this split:** Shiki is server-only (large bundle, Node-only). The async server section pre-renders the HTML; the copy button is a tiny client island. Same approach for any "code preview" block. --- ## 7. Stats bar (derived counts) A thin, dense bar right after hero. Counts derive from data sources you already have (manifests, package.json, env), not hardcoded. ```tsx import { manifest as blocksManifest } from "@vireya/blocks/showcase"; export const StatsSection = () => { const items = [ { label: "Components", value: "120+" }, { label: "Blocks", value: `${blocksManifest.length}` }, { label: "License", value: "MIT + Commercial" }, ]; return (

{item.label}: {item.value}

); }; ``` ```css .bar { display: grid; grid-template-columns: repeat(4, 1fr); border: 1px solid var(--v-secondary-border); border-radius: var(--v-radius-xl); background: var(--v-background-fill); overflow: hidden; } .cell { display: flex; flex-direction: column; gap: var(--v-height-4); padding: var(--v-height-20) var(--v-width-24); border-left: 1px solid var(--v-secondary-border); } .cell:first-child { border-left: none; } @media (max-width: 720px) { .bar { grid-template-columns: repeat(2, 1fr); } } ``` --- ## 8. One-off branded accent zone (without polluting the global accent) Sometimes a single page (landing, marketing, illustration) wants a distinct accent that shouldn't bleed into the rest of the app. Don't override `--v-accent-*` globally — scope a parallel tier under a class. ```css /* globals.css */ .landing { /* Landing-page-only example accent. Used by illustrations and example surfaces; never read by core Vireya components. */ --v-accent-example-fill: hsl(150 80% 38%); --v-accent-example-foreground: hsl(0 0% 98%); --v-accent-example-border: hsl(150 50% 24%); } ``` ```tsx

{/* sections inside can read var(--v-accent-example-fill, var(--v-accent-fill, var(--v-primary-fill))) */}

``` **Why a custom prefix (`--v-accent-example-*`) and not `--v-accent-*` directly:** - Scoped to the landing class only — the rest of the app keeps whatever accent is set globally (or no accent at all). - Doesn't break the cross-app `accent → primary` fallback contract. - Easy to grep and remove later when the section hierarchy changes. --- ## 9. RSC + namespace block exports — when to mark `"use client"` Vireya blocks expose a namespace object (`PricingTiers.Root`, `ContactSplit.Root`, `FAQTwoColumn.Root`). When that namespace is **defined inside a `"use client"` module** (because the block uses `createContext` or browser APIs), React's RSC layer rewrites the namespace into a client reference. Property access on a client reference from a Server Component returns `undefined` — so `PricingTiers.Root` becomes `undefined` and you get **"Element type is invalid... got: undefined"** at render. **Fix:** mark the consumer section as `"use client"`. This puts both the consumer and the block's chunk in the same client boundary; namespace property access works normally. ```tsx "use client"; // <- required, even for sections without state of their own import { PricingTiers } from "@vireya/blocks/pricing/tiers"; export const PricingSection = () => ( ... ); ``` Rule of thumb: if the block uses `createContext` internally, your consumer section needs `"use client"`. When in doubt, just add it — the cost is one extra client component, the benefit is no mysterious render crash. --- ## 10. Catalog rail (illustration-first preview cards) A rail-style preview of a category (blocks family, chart family, etc.). Illustration on top fills the visible area; meta below stays compact. ```tsx

{/* large SVG illustration, not a small icon */}

{title} {count} variants

`–`