Spectrum Design Data
  • Components
  • Tokens
  • Registry
  • AI
  • Specification
  • Tools
    •
    Draft Specification (v1.0.0-draft) — This specification is under active development. Normative text and schemas may change before the stable 1.0.0 release.

    Platform manifest

    Spec version: 1.0.0-draft (see Overview)

    This document defines the platform manifest: how a platform implementation repository declares its relationship to foundation design data — version pin, inclusion filters, typed overrides, and extensions.

    Manifest document

    A manifest MUST conform to manifest.schema.json (canonical $id: https://opensource.adobe.com/spectrum-design-data/schemas/v0/manifest.schema.json).

    Required fields

    Field Type Description
    specVersion string MUST be 1.0.0-draft for documents targeting this draft.
    foundationVersion string Pin to a released foundation version (semver or tag string).

    Optional fields

    Field Type Description
    include array of string Semantic queries selecting subsets of foundation tokens to materialize.
    exclude array of string Queries removing tokens from the included set.
    overrides array of object Typed overrides; each entry MUST preserve the target token’s value type.
    extensions object New tokens or mode sets introduced at the platform layer.

    include / exclude

    NORMATIVE: Each entry MUST be a non-empty string that parses as a valid query expression per Query. An entry that fails to parse, or that references a key outside the supported query key list, is a Layer 2 conformance error (SPEC-039 manifest-query-parseable).

    See Query — Formal grammar for the EBNF and Query — Supported keys for the normative list of allowed keys.

    Migration note (from earlier 1.0.0-draft revisions): Prior revisions instructed implementations to treat manifest query values as opaque identifiers. That clause is lifted as of this revision. Any manifest that uses non-query strings in include/exclude must be updated to use valid query notation; the SPEC-039 rule reports column-level parse errors to guide migration.

    overrides

    Each override object MUST include enough information to identify a target token and supply a replacement value or $ref compatible with the target’s type.

    NORMATIVE: Overrides MUST NOT change the resolved type of the token (aligns with Cascade — type safety).

    extensions

    RECOMMENDED: extensions follows the same structural conventions as foundation token files (tokens, mode sets) and SHOULD be validated with the same Layer 1 and Layer 2 rules.

    extensions.formatting

    A platform MAY declare formatting rules that control how structured name objects are serialized into flat token name strings for that platform. See Taxonomy — Platform formatting configuration for motivation and examples.

    Field Type Description
    conceptOrder array of string Ordered list of name object field names for serialization. Each entry MUST be a declared field name from the design system's field catalog (see Token format — Name object). Omitted fields are appended in the default order defined by each field declaration's serialization.position (see Taxonomy — Default serialization).
    casing string One of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE_CASE. Default: kebab-case.
    delimiter string Character(s) separating concepts in the serialized string (e.g. -, _, ., /). Default: -.
    abbreviations object Map of full term → abbreviated form (e.g. { "background": "bg" }). Abbreviations are applied after concept ordering and before casing.

    NORMATIVE: When extensions.formatting is absent, the default serialization defined in Taxonomy is used.

    NORMATIVE: A formatter applying extensions.formatting MUST produce deterministic output — the same name object and formatting configuration MUST always yield the same string.

    Validation

    NORMATIVE: Manifests MUST pass Layer 1 JSON Schema validation.

    RECOMMENDED: Validators resolve foundationVersion against a registry or lockfile and report mismatches as errors or warnings per product policy.

    Automated upgrades

    OPTIONAL: Workflows MAY open upgrade PRs when foundationVersion lags the latest release; details are out of scope for this document (see #715).

    Relationship to product context

    The platform manifest is the Layer 2 context document. For Layer 3 (product-layer) context — rationale, overrides, and extensions specific to a product team's working copy — see Product context.

    References