S&G Field Kit

S&G Field Kit is Sanford & Grant's code-first React interface foundation. It supplies shared semantic tokens and accessible components without making every project look alike.

Start here: read the default design contract, review the design profile index, then install the package, read the consumer guide, and compose from the component catalog. The detailed design system is the complete token and behavior contract.

DESIGN.md follows the Google Labs alpha format consumed by Open Design: YAML front matter contains normative tokens, while the Markdown body contains the ordered design rationale. Validate it with npx --yes @google/design.md lint DESIGN.md.

Operating model

• Code is the implementation source of truth. Components are designed, viewed, and refined in the browser.
• Design contracts guide agents. Each complete theme is documented as a self-contained Open Design DESIGN.md; the root document is the default profile.
• Storybook is rendered proof. Use it to inspect states and responsive behavior after implementing against the design contract.
• Projects own their expression. Field Kit supplies the common structure; each project supplies its theme, content density, imagery, and special patterns.

Showcase

The legacy Vinext showcase is retired. Storybook is now the only active Field Kit reference surface:

npm run dev       # start Storybook at http://localhost:6006
npm run build     # build the static Storybook reference

The public package build remains separate under npm run build:package.

Validate the agent-facing design contract with:

npm run design:verify

Storybook documentation map

Open Guides → Introduction first. It explains the ownership boundary, the review workflow, and the documentation contract for adding or consuming a component. The rest of the reference is organized by decision:

• Foundations — semantic appearance, typography, and system-wide rules.
• Components — one reusable UI responsibility with live Controls, composition, and states.
• Patterns — repeated multi-component compositions that remain domain-neutral.
• Examples — complete application shells and full-page responsive relationships.

Component documentation should answer the same questions every time: what the component is for, how it composes, which states matter, how it behaves responsively, and what accessibility behavior a consumer must preserve. Use the live Storybook examples as the rendered proof, and keep implementation and consumer-boundary decisions in the repository docs.

Install

npm install @spence-wright/field-kit

Import the stylesheet once at the application root, then import components from the package entrypoint:

import "@spence-wright/field-kit/styles.css";
import { Button, Card, CardContent } from "@spence-wright/field-kit";

Field Kit ships one default theme on :root and .dark. With no color-mode class, every project follows the operating-system preference; use .light or .dark on the root for an explicit override. Customize brand colors with the publishable field-kit CLI, then import the generated CSS after the Field Kit stylesheet (see THEME_RECIPE.md). Surface recipes use data-neutral (4 built-in) and typography uses data-type-theme (5 built-in). Keep product content, compositions, and interaction orchestration in the consuming application.

Sketch handoff

Field Kit also includes a generated Sketch Library for design consumption. Code remains the source of truth; regenerate the Library after token changes with npm run export:sketch, then verify the open-format artifact with npm run verify:sketch. See designs/sketch/README.md for the Library contents and workflow.

Penpot handoff

Field Kit also exports a Penpot token package with independent Product, Mode, Neutral, and Typography theme groups. Generate and verify it with npm run export:penpot and npm run verify:penpot, then import designs/penpot/field-kit-tokens.json into a shared Penpot file. See designs/penpot/README.md for the import and ownership workflow.

New-project setup

npm install @spence-wright/field-kit
npx field-kit theme --seed "#2563eb" --out ./src/field-kit-theme.css

import "@spence-wright/field-kit/styles.css";
import "@spence-wright/field-kit/fonts-google.css";
import "./field-kit-theme.css";

<html data-neutral="soft-canvas" data-type-theme="studio">
  <head>
    <meta name="color-scheme" content="light dark" />
  </head>
</html>

No class means system light/dark mode. Add class="light" or class="dark" to <html> when the user explicitly chooses a mode. The exported applyColorMode helper applies those classes from application controls.

Use AppSidebar as the default application shell:

<AppSidebar
  app={{ name: "Field Kit", subtitle: "Design system", icon: PencilRuler }}
  groups={[{ label: "Workspace", items: [{ label: "Overview", icon: House, href: "/" }] }]}
  fixed
>
  <PageHeader title="Overview" />
</AppSidebar>

Use fixed for a full-page application shell: it pins the desktop rail while page content scrolls, and keeps the compact mobile header sticky. Leave it off for contained previews and embedded compositions.

Typography uses four responsive heading roles and three body roles. Start with the complete type-heading-* and type-body-* classes; add type-compact for dense interface text or type-reading for long-form content. The complete sizing, leading, tracking, weight, and spacing contract is documented in DESIGN_SYSTEM.md and demonstrated in Foundations → Typography in Storybook.

Visual component editing

Run Storybook while working on a component:

npm run storybook

Open http://localhost:6006, choose a component's Playground story, and edit its serializable props in the Controls panel. Use the toolbar to compare light/dark mode, action theme, canvas, and type recipes. Click the component to inspect callback behavior in Actions.

To keep a chosen configuration, use Storybook's Update story action in the Controls panel. Storybook writes the changed args back into the corresponding src/stories file, so the saved configuration is committed with Field Kit and remains visible to every consumer reviewing the reference. Changes to the actual component implementation still belong in src/components/ and src/styles.css; Storybook then hot-reloads those changes across the stories. This keeps visual exploration fast without silently changing the public component API.

For component-owned recipe changes, open Foundations → Component Studio → Playground. Choose a registered component family, adjust its recipe fields against the live preview, and review the affected src/component-recipes.css block. Save component recipe writes only the selected component's allowlisted fields through the local Storybook server; it never writes global semantic tokens in src/styles.css, JSX, accessibility behavior, public props, or consumer-specific compositions. Use Storybook's built-in Update story action when the desired change is only a saved example configuration.

Remote editing over Tailscale

If the repository and Storybook run on a home Mac mini, install Tailscale on both the Mac mini and the remote device, then run this on the Mac mini:

npm run storybook:tailnet

The first run may ask you to enable Tailscale HTTPS. It starts Storybook on the Mac mini and publishes it privately through Tailscale Serve. Open the https://…ts.net address printed by Tailscale from the other device while Tailscale is connected. Stop the private route with:

npm run storybook:tailnet:off

This uses Tailscale Serve, not Funnel or router port forwarding. Because Component Studio can write approved component recipes into the local source tree, only expose this to devices and users you trust in your tailnet. The Mac mini must remain awake, online, and running the command.

License

MIT © Sanford & Grant