Design tokens

src/lib/appearance.ts is the pure appearance configuration. The token generator uses scripts/lib/appearance-tokens.mjs to refresh colors, palettes, materials, effects and radii in tokens/aureform.tokens.json and src/styles/tokens.css, including --af-control-color-1 through --af-control-color-4 for gradient controls. Semantic colors describe purpose; primitive colors describe a value. Counts come from generated output. Customize the source configuration or Studio colors.

Palettes, materials and type

Choose Aurora, Violet, Ocean, Mint, Ember or Rose in Light or Dark. Aurora is the default, with Manrope for the modern interface; Instrument Serif is an optional editorial display style. Each configuration resolves 33 shades: 11 steps for each of its primary, secondary and tertiary colors. Materials are flat, elevated, glass and gradient.

Depth with intention

Soft shadows, gradients, glass and hover states share appearance-aware tokens. Card accepts flat, elevated, glass or gradient through its additive appearance prop. Button and Badge accept solid, soft, outline, glass or gradient alongside their existing variant props. Button also accepts shape="rounded", "pill" or "square" with its existing size, loading and disabled controls.

A complete appearance example

Save this as a client component in a host with the kit’s global styles and fonts, such as the CLI starter. AppearanceScope isolates its Ocean configuration; the button switches Light/Dark locally without changing the rest of your application.

"use client";

import { useState } from "react";
import { AppearanceScope } from "@/components/appearance-provider";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card, CardHeader, CardTitle, CardContent,
} from "@/components/ui/card";
import { createAppearance } from "@/lib/appearance";

export default function AppearanceExample() {
  const [appearance, setAppearance] = useState(
    () => createAppearance("ocean", "light"),
  );

  return (
    <AppearanceScope appearance={appearance} className="p-6">
      <Card appearance={appearance.material}>
        <CardHeader>
          <Badge appearance="soft">{"Ocean palette"}</Badge>
          <CardTitle>{"Your palette, your surface"}</CardTitle>
        </CardHeader>
        <CardContent>
          <Button
            appearance="gradient"
            onClick={() => setAppearance((current) => ({
              ...current,
              theme: current.theme === "light" ? "dark" : "light",
            }))}
          >
            {"Switch Light / Dark"}
          </Button>
        </CardContent>
      </Card>
    </AppearanceScope>
  );
}

A considered rhythm

Choose Off, Gentle or Expressive motion. GSAP adds finite entrances and Lenis smooths the landing on fine pointers; the workspace keeps native scrolling. Motion Off and the operating system’s reduced-motion preference disable decorative movement. Useful content stays visible before JavaScript loads.

import { MotionSystem } from "@/components/motion-system";

<MotionSystem smoothScroll>
  <h1 data-motion="intro">A good beginning.</h1>
  <section data-motion="reveal">Always-visible content</section>
</MotionSystem>

// Install the reusable runtime:
// node bin/aureform.mjs add motion-system --cwd ../my-product

Change once, regenerate deliberately

# Customize palettePresets / createAppearance in src/lib/appearance.ts
pnpm tokens
pnpm registry
# Generated: tokens/aureform.tokens.json and src/styles/tokens.css
# pnpm tokens uses Node --experimental-strip-types.
# Review matching Figma variables before releasing.

Spacing follows a 4 px rhythm. Appearance radius is adjustable from 0 to 24 px; the current 16 px default resolves small/medium/large/extra-large aliases to 6.4/10.4/16/16 px. These values follow the configuration. Custom colors belong in src/lib/appearance.ts or in the Studio. Editing generated token JSON will be overwritten by pnpm tokens.

Studio, presets and exports

In Appearance Studio, choose a palette, edit its colors and material, then save, apply or delete a named preset. Settings and presets remain in your browser. Export JSON for a complete configuration, CSS for resolved variables, or React for a complete configured example. Import an exported appearance JSON file or paste its contents; validation runs before applying it.

For a custom host theme, load the Studio’s CSS export after the kit styles. If AppearanceProvider manages that host, apply the JSON configuration through the provider instead: its resolved values control the document. Appearance JSON uses schema version 1 independently of the kit release.

Bind purpose to components

Prefer semantic classes and appearance props over hardcoded colors. The source includes reduced-motion rules, shared focus rings and bundled font licenses. Recheck contrast in both themes after changing colors.