# Snurble docs full snapshot This file concatenates the markdown twins for every page in apps/docs. # Snurble design system Snurble packages the shared design-system contract extracted from workv2 into design tokens and Astro primitives. The docs site explains the durable foundations, primitive families, and adoption path without relying on one-off project history. ## Start here - Foundations: repo roles, foundation coverage, and extraction status live on /foundation. - Primitive families: shell, profile/social, project, and experience pages document the shared package surface. - Adoption path: the migration and release-readiness guides explain how consumers adopt published packages safely. ## Current package surface Shared families currently include: - Foundations: Layout, PageShell, Hero, Section, Panel, Stack, DataTable, MetaList, CodeSnippet - Shell primitives: FontAssets, JsonLd, SkipLink - Profile/social primitives: ProfileHero, SocialLinks, DecoratedHeading - Project primitives: ProjectCard, ProjectGrid - Experience primitives: ExperienceCard, ExperienceList, SkillIcon, SkillIconList ## Recommended reading order 1. Foundations 2. Primitive families 3. Adoption and migration 4. Release and publishing --- # Experience Primitives These primitives help present work history once experience data has already been normalized into display-ready values. ## Contracts - ExperienceCard renders role, company, trusted description HTML, and time range. - ExperienceList renders a semantic unordered list with stack spacing. - SkillIconList provides optional title text and spacing for skill badges. - SkillIcon is slot-only and expects consumer-provided icon or label markup. ## Trusted boundary ExperienceCard.description is rendered with set:html. Only pass sanitized or otherwise trusted rich text. ## Consumer responsibilities - Fetch and normalize experience data before rendering. - Keep datetime-compatible strings aligned with visible date text. - Supply accessible icon markup and any richer logo labeling behavior outside the primitive. - Preserve list semantics by wrapping each experience entry in li elements. --- # Snurble foundations Snurble extracts durable design-system contracts from workv2 into shared packages, then validates those contracts in mattriley.tools and future adopters. ## Repository roles - workv2/webclient: foundation reference for the visual and structural source of truth. - Snurble: shared system that publishes @matt-riley/design-tokens and @matt-riley/ui-astro. - mattriley.tools: first proving adopter of the shared packages. ## Foundation coverage Current coverage is organized around durable families instead of temporary milestones: - Foundations — shipped - Shell primitives — shipped - Profile/social primitives — shipped - Project primitives — shipped - Experience primitives — shipped - Adoption/migration — documented - Release/publishing — documented ## Extraction status - Token and foundation layer: aligned - Foundation families: shipped - Remaining boundaries: consumer-owned data fetching, ranking, README rendering, and app-specific metadata policy remain outside the shared package surface. ## Recommended reading order Move from foundations to primitive families, then adoption/migration, then release/publishing. --- # mattriley.tools migration cookbook This cookbook documents the shared-component handoff for mattriley.tools, the first proving Snurble consumer. It also serves as the repeatability guide for any sibling Astro consumer adopting the same shared surface. ## Migration boundary - Snurble package-contract changes and this cookbook page can ship independently of a consumer rollout branch. - Local-only smoke validation may use packed tarballs or file refs, but those refs do not get committed. - Committed consumer manifest switches wait for published prerelease package versions. ## Consumer boundary invariants - Shared helpers live in packages/ui-astro. - Route inventory and Markdown generation stay site-local to each consumer. - The current delivery path is static-first; runtime negotiation remains deferred. - Consumer-owned layout wrappers, favicon handling, and page metadata remain local. ## Component mapping Use the shared surface for layout, shell, data-table, panel, stack, meta-list, and code-snippet chrome while keeping generated data, README rendering, favicons, and route-specific metadata local to the consumer. ## Wrapper pattern Shared Layout should own token import and document scaffolding, but mattriley.tools still keeps a small local wrapper for title suffixes, favicons, remaining global CSS, and page-owned main semantics. ## Local validation loop Pack both Snurble packages, install them into a clean mattriley.tools checkout, and rerun lint, tests, and build before committing any registry-backed adoption. --- # Profile & Social Primitives These primitives cover the most common profile-page building blocks while leaving content strategy, icon sourcing, and section structure to the consumer. ## Covered primitives - ProfileHero — centered avatar, name, and subtitle for a person or creator profile page. - SocialLinks — navigation landmark containing external profile links with hover and focus affordances. - DecoratedHeading — stylized SVG heading treatment for decorative section labels. ## Consumer responsibilities - Provide meaningful avatar alt text. - Supply accessible social link labels and vetted external URLs. - Pair DecoratedHeading with a semantic heading when it labels a real section. - If SVG or component-based icons are needed, wrap SocialLinks instead of treating it as a raw HTML injection point. ## Composition A typical profile page composes ProfileHero, SocialLinks, and a decorated section heading while keeping page structure and content ownership local. --- # Project Primitives ProjectCard and ProjectGrid render project summaries without taking over the consumer's data pipeline. ## Contracts - ProjectCard renders the card, linked title, description, optional stars, languages, and topics. - ProjectGrid renders the semantic list and responsive grid wrapper. - Fetching, ranking, filtering, grouping, and empty states stay outside the primitives. ## Security and accessibility - Project URLs are validated before rendering into href. - Dangerous schemes are replaced with #. - Language colors are validated before they reach inline styles. - Keep ProjectGrid children wrapped in li elements so list semantics stay intact. - Use descriptive project names so link text remains meaningful for assistive technology. ## Example usage Map already-ranked project data into a ProjectGrid and render one ProjectCard per list item. --- # Snurble release readiness Use this runbook to publish Snurble prereleases, move consumers onto registry installs, and enforce the gates that keep later adoption safe. ## Manual prerelease contract - Start with a manual prerelease so package contents, versioning, and registry auth stay explicit. - Use the same prerelease version string for both shared packages. - Validate before publishing and publish with the next dist-tag. ## Consumer install contract - Consumers install real prerelease versions from the registry and commit those versions in the manifest and lockfile. - Do not commit file: refs or local tarball dependencies as the long-term state. - Public imports stay on package entrypoints. ## Rollback and adoption gates - Revert consumers to the last known-good package versions instead of reusing a bad version. - Publish a newer prerelease before resuming rollout. - Later adopters wait until the first proving consumer has rerun validation against published prereleases. ## Automation follow-on Automate only after the manual runbook remains stable and proven in real consumer adoption. --- # Shell Primitives Shell primitives help wire page-level concerns without expanding the layout API. ## Covered primitives - FontAssets — inject shared @font-face declarations used by Snurble typography tokens. - JsonLd — renders structured data in a script[type="application/ld+json"] tag. - SkipLink — provides a hidden-until-focus anchor that moves keyboard users directly to main content. - SeoMeta — renders Open Graph and Twitter card metadata in the head slot. - ServiceWorker — registers a PWA service worker on the load event. ## Core guidance - Use these primitives at the document shell layer, not inside leaf content components. - Route-specific decisions remain consumer-owned. - JsonLd input must be intentionally published and JSON-serializable. - SkipLink href values must stay internal anchors beginning with #. - SeoMeta absolute URLs are required for canonical and image fields. - ServiceWorker registration is optional and additive. --- # WorkV2 Reference This page is the visual baseline for WorkV2 alignment. Each aligned component is shown with the acceptance criteria derived from the WorkV2 webclient source of truth. ## What this page covers - Color token alignment between Catppuccin Mocha source colors and Snurble semantic tokens. - Acceptance criteria for ProfileHero, SocialLinks, DecoratedHeading, Section decorated headings, ExperienceCard, and ProjectCard. - A final acceptance checklist that records the aligned phases. ## Key alignment rules - workv2 remains the visual and structural source of truth. - Snurble re-exposes the WorkV2 palette through semantic design tokens. - DecorativeHeading stays decorative only; semantic headings must still be provided for accessibility. - Component regressions should be checked against this page after token or shared-component changes. ## Acceptance checklist Alignment is complete when badge surfaces, SkipLink, SkillIcon accessibility, SocialLinks focus, semantic tokens, and the core profile/project/experience component treatments all match the documented criteria.