Custom Foundations

When none of the 12 themes fit your project, create a new cultural foundation and generate a complete theme from it.

The Pipeline

The theme system is built as a generation pipeline. You provide a foundation JSON file with seed colors, harmony mode, and typography choices. The pipeline generates everything else:

Foundation JSON  ->  Color engine  ->  DTCG tokens  ->  CSS + Tailwind output

One file in, four artifacts out.

Using the Skill

The fastest way to create a custom foundation:

/webplatform4sync:shu

Then ask Claude to generate a theme for your cultural tradition. The skill produces a complete foundation and runs it through the pipeline.

Foundation JSON Schema

Every foundation file follows this structure:

interface FoundationData {
  $name: string;           // e.g. "swiss-international-style"
  $description: string;    // one-line cultural description
  $extensions: {
    'syncupsuite.foundation': {
      story: string;       // 2-3 sentence cultural history
      philosophy: string;  // e.g. "Wabi-sabi — beauty in imperfection"
      era: string;         // e.g. "Heian period (794–1185)"
      harmonyMode: 'golden-ratio' | 'monochromatic' | 'complementary'
                   | 'triadic' | 'analogous';
      radiusTendency: 'none' | 'subtle' | 'moderate' | 'rounded';
      typographyCategory: 'humanist-serif' | 'slab-serif'
                          | 'geometric-sans' | 'neo-grotesque'
                          | 'modern-serif' | 'transitional-serif'
                          | 'grotesque-sans';
    };
  };
  seedColors: Array<{
    hex: string;        // "#RRGGBB" exactly
    name: string;       // Name in language of origin
    tradition: string;  // Cultural context
    source: string;     // Bibliographic reference
  }>;
}

Required Fields

Every field is required. The pipeline rejects files missing any of these:

• $name and $description at the top level
• $extensions['syncupsuite.foundation'] with all six properties
• seedColors as a non-empty array
• Each seed color must have hex, name, tradition, and source

Harmony Modes

The harmony mode controls how the color engine expands your seed colors into full scales:

Mode	Hue Rotation	Best for
Monochromatic	0 degrees	Minimalist, single-hue designs
Golden Ratio	+137.5 degrees	Default -- natural, balanced palettes
Complementary	+180 degrees	High contrast, bold designs
Triadic	+120 degrees	Vibrant, multi-accent designs
Analogous	+30 degrees/step	Harmonious, nature-inspired

Radius Tendency

Controls the border-radius scale across all UI elements:

Tendency	none / xs / sm / md / lg / full
none	0 / 0 / 0 / 0 / 0 / 9999px
subtle	0 / 2 / 4 / 6 / 8 / 9999px
moderate	0 / 4 / 8 / 12 / 16 / 9999px
rounded	0 / 8 / 12 / 16 / 24 / 9999px

Complete Example

Here is the actual swiss-international.json from the themes repo:

{
  "$name": "swiss-international-style",
  "$description": "Swiss International Typographic Style — precision, clarity, grid-based order from the Basel and Zurich schools",
  "$extensions": {
    "syncupsuite.foundation": {
      "story": "Born from the Basel and Zurich schools of the 1950s, Swiss International Style prioritized objective clarity over decorative expression. Designers like Josef Müller-Brockmann and Armin Hofmann established principles of grid-based composition, asymmetric layouts, and sans-serif typography that became the global standard for corporate and informational design.",
      "philosophy": "Sachlichkeit (Objectivity) — form follows function with mathematical precision",
      "era": "1950s–present",
      "harmonyMode": "monochromatic",
      "radiusTendency": "none",
      "typographyCategory": "neo-grotesque"
    }
  },
  "seedColors": [
    {
      "hex": "#111111",
      "name": "Schwarz",
      "tradition": "Pure typographic black. The foundation of Swiss poster design and Helvetica specimens.",
      "source": "Swiss Graphic Design: The Origins and Growth of an International Style, R. Hollis"
    },
    {
      "hex": "#FAFAFA",
      "name": "Weiss",
      "tradition": "Paper white. The generous whitespace that gives Swiss design its breathing room.",
      "source": "Grid Systems in Graphic Design, Josef Müller-Brockmann"
    },
    {
      "hex": "#E8322E",
      "name": "Rot (Signal Red)",
      "tradition": "The accent of Swiss rail (SBB/CFF), national flag, and Müller-Brockmann concert posters. Pure signal with no ambiguity.",
      "source": "Swiss Style: The Graphic Design of Swiss International Style"
    },
    {
      "hex": "#6E6E6E",
      "name": "Mittelgrau",
      "tradition": "Mid-grey for secondary information hierarchy. Swiss design uses grey to create clear visual levels.",
      "source": "Typographic Design: Form and Communication, R. Carter"
    },
    {
      "hex": "#D4D4D4",
      "name": "Hellgrau",
      "tradition": "Light grey for borders, dividers, and subtle structural elements in grid systems.",
      "source": "Swiss Graphic Design"
    },
    {
      "hex": "#1A3A5C",
      "name": "Dunkelblau",
      "tradition": "Swiss corporate blue. Used in banking, insurance, and institutional communications for trust and authority.",
      "source": "Corporate Design, Wally Olins"
    }
  ]
}

Note how every seed color has a name in the source language, a cultural context, and a bibliographic reference. This is not decoration -- the metadata flows into meta.json and powers theme pickers, documentation, and cultural attribution.

Manual Creation

1. Research the Tradition

Document the cultural source material. What are the defining visual characteristics? What colors, proportions, and rhythms are characteristic? Get specific -- cite art movements, historical periods, named practitioners.

2. Create a Foundation File

Add a JSON file to packages/foundations/data/ with your theme's seed data:

# File name matches the theme slug
packages/foundations/data/your-theme-name.json

The pipeline reads this file and generates the full token set. Use the schema above and the Swiss International example as your template.

3. Generate

cd themes/
pnpm generate

This produces tokens.json, tokens.css, tailwind.css, and meta.json for your new theme.

4. Verify

pnpm build && pnpm test

The test suite runs these checks:

• Schema validation: Required fields, correct types, valid hex colors
• 20 WCAG AA contrast pairs: foreground/background combinations at 3:1 or 4.5:1 minimum
• Performance budgets: under 20KB gzipped CSS, under 500 custom properties, under 8 levels nesting depth
• Token completeness: all required semantic tokens present

Contrast warnings are non-blocking -- some cultural palettes intentionally use lower-contrast combinations. The warnings are documented so you can make an informed decision.

Single-Command Workflow

The full cycle from foundation to built theme:

cd themes && pnpm generate && pnpm test && pnpm build

If tests pass and the build succeeds, your theme is ready.

Submitting a Theme

1. Fork syncupsuite/themes
2. Add your foundation to packages/foundations/data/
3. Run pnpm generate && pnpm build && pnpm test
4. Open a pull request with cultural documentation explaining the source material

The PR should explain why these specific colors, what tradition they come from, and cite your sources. Themes without cultural documentation will not be merged.

Next Steps

• Theme Gallery -- see all 12 existing identities
• Semantic Colors -- the token API your theme will produce
• Token Governance -- how tiers interact with your tokens
• Package Reference -- the pipeline packages under the hood