6. Naming and token conventions

Local snapshot only. The workspace page is authoritative.

6.1 Authoritative current token set

Two additional authoritative sources govern adjacent naming layers and must be read alongside the token JSON, not substituted for it:

• The vocabulary Ruleset is authoritative for component property and property-value naming — camelCase properties, kebab-case values, the isX/hasX boolean convention, and the defined semantic categories (status, state, behaviour, appearance, treatment, variant, size, shape, position, placement, orientation, density). This governs component API surface, not token output identifiers.
• The type scale formula is authoritative for how PDS’s typographic scale is derived: a 16px baseline, a 1.125 (Major Second) step ratio for font size, and a Golden Ratio–derived step for line height. This is a generation formula, not a naming grammar.
  This operating model does not re-derive or restate token names, values, categories, modes, aliases, breakpoints, or platform outputs from these files. Contributors and coding agents must reference the authoritative files directly. Their current contents are an approved baseline; none of the three should be treated as a complete future-token policy until the Core-team inventory is complete.

6.2 Required use and missing-token path

Product teams and PDS contributors must use an existing PDS token when it represents the required design decision.
When no current token represents a legitimate need:

1. the team submits a token request through the common intake;
2. the request states the semantic need, affected property/theme, proposed role, existing alternatives, product evidence, accessibility impact, consumers, and release impact;
3. while the request is pending, the product team may use a hard-coded value or product-owned token;
4. the temporary value or token remains product-owned and unsupported by PDS;
5. acceptance of a Core token does not automatically migrate the product implementation.
   Temporary use is a delivery bridge, not permission to create a competing global token system.

6.3 Token decision authority

Token decisions use two required domains:

• Design Ops Product Designer: semantic intent, taxonomy, public naming, breakpoint intent, and the semantic meaning of AI-readable identifiers.
• PDP engineering lead: schema validity, alias implementation, serialization, generated outputs, build impact, platform delivery, SemVer classification, technical stability, and reliable coding-agent consumption.
  A new or changed public token requires both design and engineering go decisions. The Design Ops Lead owns Core priority and final governance after those gates pass.
  The Design Ops Product Designer governs breakpoint alignment. Engineering governs breakpoint implementation and outputs. Breakpoint changes therefore require design and engineering gates.
  AI-readable token identifiers are part of the authoritative PDS token standard, not a separate machine-only standard. Their semantic naming requires the design gate; their schema, serialization, stability, and agent consumption require the engineering gate.
  No separate fr-CA token set is created. Locale behavior is handled through flexible components, built-in-string localization, accessible naming, and locale-aware formatting as defined in section 7.

6.4 Token compatibility

Published semantic and component-token identifiers and meanings are public API:

• additions are minor changes;
• a compatible correction may be patch only when engineering confirms it is non-breaking;
• deprecation is announced in a minor release with a supported replacement or alias and migration guidance;
• removal, breaking rename, or incompatible semantic change occurs only in a major release.
  Value changes must be reviewed for visual, accessibility, and consumer breakage; a token-name change is not the only possible breaking change.

6.5 Open token decisions

Open — pending Core team: detailed token inventory and future-token policy. The controlled vocabulary ruleset and the type scale formula narrow this item for component-property naming and typographic derivation specifically, but do not resolve it. Inventory and confirm:

• current semantic categories and primitives;
• naming grammar and namespaces for token (not component-property) identifiers;
• aliases and layer boundaries;
• light/dark and other modes;
• state and scale terms, and their relationship to the vocabulary ruleset’s state/status/behaviour categories;
• component-token boundaries;
• generated outputs and supported platforms;
• breakpoint inventory and output alignment;
• known duplicates, gaps, and unresolved literals;
• stable identifier requirements for AI context;
• required validation, linting, and migration controls;
• which present JSON structures become mandatory for future tokens.
  No rule in this list is settled merely because a pattern appears in the current JSON.