{ "$format": "design-spec@0.1", "$description": "shupp.dev's default skin, written as a design spec. Extracted from src/layouts/Layout.astro, src/components/Header/SideNav.astro, src/pages/index.astro and docs/design-specs.md. Values are what ships today; drift is listed under knownIssues instead of being silently corrected.", "meta": { "name": "shupp.dev", "slug": "shupp", "version": "0.1.0", "updated": "2026-10-26", "source": { "repo": "https://github.com/shuppel/shupp-dev", "tokensFile": "src/layouts/Layout.astro", "prose": "docs/design-specs.md" }, "modes": ["light", "dark"], "defaultMode": "dark", "modeSwitch": "Class `dark` on . Dark unless localStorage.theme === 'light'.", "skins": { "contract": "A skin is a stylesheet that remaps the role tokens below onto another system's values. Components never change; only the role layer does.", "available": ["site", "prism", "void"] } }, "identity": { "thesis": "A calm, botanical workspace for a person who builds apps for hoomans: sage, olive and citron on a plum-black ground, a handwritten wordmark, and surfaces that move like liquid when touched.", "invariants": [ "One handwritten display face (Shupp) appears only in the wordmark and page-level headings.", "Every accent comes from the five brand colors; there is no blue, red or purple in the chrome.", "Surfaces lift on hover with the liquid easing curve; nothing snaps.", "Labels are small, uppercase Cairo with wide tracking; body copy is Hind at a relaxed 1.6–1.75 leading.", "A single animated conic outline marks the most important card on a page, and only one." ], "identityTest": "Swap the palette for greys. If the handwritten wordmark, the tracked uppercase labels, the pill buttons and the liquid lift still read as this site, the identity holds." }, "tokens": { "color": { "brand": { "dark": { "$type": "color", "$value": "#14080E", "css": "--color-dark", "name": "Plum black", "use": "Body text on light. Canvas in dark mode." }, "secondary": { "$type": "color", "$value": "#49475B", "css": "--color-secondary", "name": "Cool slate", "use": "Secondary text, primary button fill (light), gradient partner." }, "tertiary": { "$type": "color", "$value": "#799496", "css": "--color-tertiary", "name": "Sage teal", "use": "Links, borders, focus ring, eyebrow labels. Not for body text on white." }, "accent": { "$type": "color", "$value": "#ACC196", "css": "--color-accent", "name": "Olive", "use": "Headshot ring, dark-mode accent text and active states." }, "light": { "$type": "color", "$value": "#E9EB9E", "css": "--color-light", "name": "Pale citron", "use": "Dark-mode highlight, primary button text (light), gradient terminus." } }, "role": { "background": { "css": "--background-color", "light": "#f9fafb", "dark": "{color.brand.dark}", "use": "Page canvas" }, "backgroundAlt": { "css": "--background-alt", "light": "#f1f5f9", "dark": "{color.brand.secondary}", "use": "Subtle sectioning, inline code" }, "surface": { "css": "--surface", "light": "#ffffff", "dark": "#23232b", "use": "Cards, hero, previews" }, "surfaceElevated": { "css": "--surface-elevated", "light": "#ffffff", "dark": "#2a2a33", "use": "Reserved for stacked surfaces" }, "surfaceMuted": { "css": "--surface-muted", "light": "#f8f8f6", "dark": "#1a1a22", "use": "Inset and preview wells" }, "text": { "css": "--text-color", "light": "{color.brand.dark}", "dark": "#f3f4f6", "use": "Running text" }, "textStrong": { "css": "--text-strong", "light": "{color.brand.dark}", "dark": "#f3f4f6", "use": "Headings, emphasis" }, "textLight": { "css": "--text-light", "light": "{color.brand.secondary}", "dark": "{color.brand.light}", "use": "Secondary text" }, "textMuted": { "css": "--text-muted", "light": "#6b7280", "dark": "#a5a5b5", "use": "Dates, metadata" }, "primary": { "css": "--primary-color", "light": "{color.brand.tertiary}", "dark": "{color.brand.tertiary}", "use": "Links at rest" }, "primaryStrong": { "css": "--primary-dark", "light": "{color.brand.dark}", "dark": "{color.brand.accent}", "use": "Links on hover" }, "border": { "css": "--border-color", "light": "{color.brand.tertiary}", "dark": "{color.brand.tertiary}", "use": "Defined borders" }, "borderSubtle": { "css": "--border-subtle", "light": "rgba(121,148,150,0.15)", "dark": "rgba(233,235,158,0.10)", "use": "Card outlines, dividers" }, "hoverTint": { "css": "--hover-tint", "light": "rgba(121,148,150,0.08)", "dark": "rgba(233,235,158,0.08)", "use": "Background wash on hover" }, "eyebrow": { "css": null, "light": "{color.brand.tertiary}", "dark": "{color.brand.accent}", "use": "Uppercase section labels (de facto role, no token yet)" } }, "gradient": { "brandWash": { "$value": "linear-gradient(135deg, rgba(121,148,150,0.1), rgba(172,193,150,0.1))", "use": "Card hover wash" }, "headingInk": { "light": "linear-gradient(45deg, {color.brand.dark}, {color.brand.secondary})", "dark": "linear-gradient(45deg, #f3f4f6, {color.brand.accent})", "use": "Hero h1 as clipped text" }, "quantum": { "$value": "conic-gradient(from var(--angle), transparent 0%, color-mix(in srgb, {color.brand.tertiary} 70%, transparent) 18%, color-mix(in srgb, {color.brand.accent} 85%, transparent) 30%, color-mix(in srgb, {color.brand.light} 70%, transparent) 42%, transparent 60%)", "use": "Animated outline on the one featured card" }, "badge": { "sage": "linear-gradient(135deg, {color.brand.tertiary}, {color.brand.accent})", "slate": "linear-gradient(135deg, {color.brand.secondary}, {color.brand.tertiary})", "plum": "linear-gradient(135deg, {color.brand.dark}, {color.brand.secondary})" } } }, "font": { "family": { "display": { "css": "--font-main-header", "$value": "'Shupp', 'Maitree', serif", "source": "/fonts/Shupp.otf (handwritten, one weight); Maitree from Google Fonts", "use": "Wordmark, h1, h2" }, "heading": { "css": "--font-secondary-header", "$value": "'Cairo', sans-serif", "source": "Google Fonts 300–700", "use": "h3–h6, labels, buttons, nav" }, "body": { "css": "--font-body", "$value": "'Hind', sans-serif", "source": "Google Fonts 300–700", "use": "Body, descriptions, meta" }, "mono": { "css": null, "$value": "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace", "use": "Inline code" } }, "scale": { "eyebrow": { "$value": "0.68rem", "px": 11, "family": "heading", "weight": 700, "tracking": "0.14em", "case": "upper", "use": "Section labels" }, "label": { "$value": "0.75rem", "px": 12, "family": "body", "weight": 500, "tracking": "0.08em", "case": "upper", "use": "Type chips, card kickers" }, "meta": { "$value": "0.8rem", "px": 13, "family": "body", "weight": 500, "use": "Dates, link chips" }, "small": { "$value": "0.9rem", "px": 14, "family": "body", "weight": 400, "leading": 1.5, "use": "Card descriptions" }, "nav": { "$value": "0.95rem", "px": 15, "family": "heading", "weight": 500, "tracking": "0.01em", "use": "Navigation" }, "body": { "$value": "1rem", "px": 16, "family": "body", "weight": 400, "leading": 1.6, "use": "Default" }, "lead": { "$value": "1.05rem", "px": 17, "family": "body", "weight": 400, "leading": 1.75, "use": "Bio, intro paragraphs" }, "title": { "$value": "1.1rem", "px": 18, "family": "heading", "weight": 600, "use": "Card titles" }, "h3": { "$value": "1.5rem", "mobile": "1.25rem", "px": 24, "family": "heading", "weight": 500, "leading": 1.2 }, "h2": { "$value": "2rem", "mobile": "1.75rem", "px": 32, "family": "display", "weight": 600, "leading": 1.2 }, "h1": { "$value": "2.5rem", "mobile": "2rem", "px": 40, "family": "display", "weight": 600, "leading": 1.2 }, "hero": { "$value": "2.4rem", "mobile": "1.9rem", "px": 38, "family": "display", "weight": 700, "leading": 1.1, "use": "Hero name, gradient ink" } } }, "space": { "$description": "8px base, in rem so it follows the reader's font size.", "0.5": { "$value": "0.25rem", "px": 4, "use": "Tight inline gaps" }, "1": { "$value": "0.5rem", "px": 8, "use": "Inside components" }, "1.5": { "$value": "0.75rem", "px": 12, "use": "Card content gaps" }, "2": { "$value": "1rem", "px": 16, "use": "Card padding, grid gap" }, "3": { "$value": "1.5rem", "px": 24, "use": "Section side padding, title-to-content" }, "4": { "$value": "2rem", "px": 32, "use": "Hero padding, page padding" }, "6": { "$value": "3rem", "px": 48, "use": "Layout gap" }, "7": { "$value": "3.5rem", "px": 56, "use": "Between reading sections" }, "8": { "$value": "4rem", "px": 64, "use": "Between major sections" } }, "radius": { "xs": { "$value": "3px", "use": "Inline code" }, "sm": { "$value": "6px", "use": "Link chips" }, "md": { "$value": "10px", "use": "Nav items, icon badges" }, "lg": { "$value": "12px", "use": "Cards" }, "xl": { "$value": "18px", "use": "Hero card" }, "pill": { "$value": "30px", "use": "Buttons, tags" }, "circle": { "$value": "50%", "use": "Headshot, avatar, theme toggle" } }, "shadow": { "card": { "css": "--card-shadow", "light": "0 4px 6px -1px rgba(20,8,14,0.1), 0 2px 4px -1px rgba(20,8,14,0.06)", "dark": "0 4px 16px -1px rgba(0,0,0,0.5), 0 2px 4px -1px rgba(0,0,0,0.3)" }, "rest": { "$value": "0 2px 8px rgba(20,8,14,0.04)" }, "hover": { "$value": "0 4px 16px rgba(20,8,14,0.08)" }, "hero": { "$value": "0 6px 28px rgba(20,8,14,0.06)" }, "lift": { "$value": "0 7px 14px rgba(20,8,14,0.2), 0 3px 6px rgba(20,8,14,0.1)", "use": "Button hover" }, "focusRing": { "css": "--focus-ring", "light": "0 0 0 3px rgba(121,148,150,0.45)", "dark": "0 0 0 3px rgba(233,235,158,0.55)" } }, "motion": { "easing": { "liquid": { "$value": "cubic-bezier(0.25, 0.8, 0.25, 1)", "use": "Every lift, entrance and nav transition" }, "standard": { "$value": "ease", "use": "Color and opacity micro-changes" }, "snappy": { "$value": "cubic-bezier(0.4, 0, 0.2, 1)", "use": "Page transitions on mobile" } }, "duration": { "press": { "$value": "100ms", "use": "Button :active" }, "micro": { "$value": "200ms", "use": "Hover color, chip lift" }, "base": { "$value": "300ms", "use": "Card and button lift, view transition" }, "entry": { "$value": "700ms", "use": "Hero fade-up" }, "page": { "$value": "800ms", "use": "
fluid entry" }, "ambient": { "$value": "14s", "use": "Quantum outline rotation, linear, infinite" } }, "keyframes": { "fluidEntry": "from { opacity: 0; transform: translateY(10px) scale(0.98) }", "liquidFadeIn": "from { opacity: 0; transform: translateY(20px) scale(0.95) }" }, "hover": { "card": "translateY(-2px)", "button": "translateY(-2px) scale(1.03)", "press": "translateY(1px) scale(0.98)", "chip": "translateY(-1px)" }, "reducedMotion": "Under prefers-reduced-motion: reduce, all durations collapse to 0.01ms, hover transforms are removed and the quantum outline stops." }, "layout": { "breakpoints": { "mobile": { "$value": "768px", "means": "Side nav collapses to a top bar; main gets 4.5rem top padding; type steps down." }, "narrow": { "$value": "1100px", "means": "Main drops its max-width and fills the space right of the nav." } }, "width": { "page": { "$value": "1200px", "use": "Outer content limit" }, "sideNav": { "$value": "240px", "use": "Fixed left navigation" }, "reading": { "$value": "860px", "use": "Press-kit sections and hero" } }, "pagePadding": { "desktop": "2rem", "mobile": "1rem" }, "zIndex": { "sideNav": 100, "skipLink": 9999 } }, "icon": { "library": "Phosphor (@phosphor-icons/react)", "weight": "duotone", "sizes": { "chip": 14, "inline": 16, "badge": 20 }, "component": "src/components/Icon/Icon.astro", "minimum": "14px on screen; 12px only for decoration" } }, "components": { "button": { "purpose": "The single call to action in a region.", "anatomy": ["label"], "base": { "font": "heading 500", "padding": "0.5rem 1.5rem", "radius": "{radius.pill}", "transition": "all {motion.duration.base} {motion.easing.liquid}" }, "variants": { "primary": { "light": { "bg": "{color.brand.secondary}", "fg": "{color.brand.light}" }, "dark": { "bg": "{color.brand.accent}", "fg": "{color.brand.dark}" }, "hover": "bg → {color.brand.dark} (light)" }, "secondary": { "light": { "bg": "transparent", "fg": "{color.brand.dark}", "border": "2px {color.brand.tertiary}" }, "dark": { "bg": "rgba(233,235,158,0.1)", "fg": "#f3f4f6", "border": "2px {color.brand.accent}" }, "hover": "fills with the border color" } }, "states": ["rest", "hover: lift + scale 1.03 + {shadow.lift}", "active: press transform, 100ms", "focus-visible: {shadow.focusRing}"], "a11y": ["Real or