Skip to content

[Theme scales/contracts] Add serializable spacing scale contracts #29

Description

@artiphishle

Summary

Add serializable spacing scale contracts to @ankhorage/contracts so apps, templates, Studio, ZORA, and future render layers can agree on the selected spacing system.

The contract should describe scale configuration and preset selection. It should not contain runtime functions or ZORA-specific component recipes.

Related ZORA parent: ankhorage/zora#158

Architecture

  • @ankhorage/contracts owns serializable scale config and preset names.
  • @ankhorage/zora owns semantic geometry recipes and component interpretation.
  • @ankhorage/surface owns low-level rendering and receives resolved values.
  • ankhorage4 / Studio can later expose theme creator controls for preset/density selection.

Scope

  • Investigate common spacing scale presets:
    • Ankhorage default
    • Tailwind
    • Material-style 4/8 grid
    • Atlassian
    • Carbon
    • Bootstrap
    • custom
  • Add serializable spacing scale types, for example:
    • ThemeSpacingPreset
    • ThemeDensity
    • ThemeSpacingScaleConfig
  • Allow custom numeric token maps while keeping presets deterministic.
  • Extend ThemeConfig with optional spacing configuration.
  • Add tests proving theme configs remain serializable and type-safe.
  • Update README/docs with the contract boundary.

Suggested shape

export type ThemeSpacingPreset =
  | 'ankhorage'
  | 'tailwind'
  | 'material'
  | 'atlassian'
  | 'carbon'
  | 'bootstrap'
  | 'custom';

export type ThemeDensity = 'compact' | 'default' | 'comfortable';

export interface ThemeSpacingScaleConfig {
  preset: ThemeSpacingPreset;
  density?: ThemeDensity;
  baseUnit?: number;
  presetVersion?: string;
  tokens?: Record<string, number>;
}

Final names may differ if a better contract shape emerges during implementation.

Acceptance criteria

  • @ankhorage/contracts exposes serializable spacing scale config types.
  • ThemeConfig can carry spacing scale selection without importing ZORA or Surface.
  • Supported preset names are explicit and documented.
  • Custom scales are possible without runtime functions in manifests.
  • Tests cover representative preset and custom configs.
  • bun run build, bun run lint:fix, and bun run test pass.

Non-goals

  • Do not implement ZORA recipe consumption in this repo.
  • Do not add component-specific spacing recipes to contracts.
  • Do not add non-serializable functions or callbacks.
  • Do not implement Studio UI in this issue.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions