Interoperability and migration
DTCG exchange, locale catalogs, design identity and reviewed migration.
DTCG 2025.10
The optional @fayegram-ai/faye-ui/theme/dtcg entry accepts portable DTCG documents and exposes resolveDTCG and resolveDTCGResolver. Source preserves metadata and references; resolved tokens are a separate frozen snapshot. The adapter performs no network or filesystem reads.
Supported structures include inherited types, root tokens, group extension, whole-token aliases, escaped JSON pointers and component references, standard simple/composite token types, ordered sets, modifiers and defaults. External references must appear in an explicit URI-to-document map. Resolver inputs are case-sensitive strings. Context products are bounded to 256; portable size/depth limits apply. Unsupported structures fail explicitly.
This is a bounded interchange profile, not a claim of universal tool compatibility. Faye UI's CSS-oriented theme value grammar differs from DTCG structured values. A design tool must perform an explicit, reviewed conversion rather than paste arbitrary token JSON into ThemeDefinition. Format and resolver specifications are available at https://www.designtokens.org/tr/2025.10/format/ and https://www.designtokens.org/tr/2025.10/resolver/.
Locale catalogs
The optional @fayegram-ai/faye-ui/provider/messages entry defines version-1 plain-text catalogs with a locale, revision and known message keys. FayeUIProvider accepts explicit catalogs; regional/script parents fall back to English per key. Parameters must retain source names. No HTML, executable interpolation, remote fetching or automatic language-pack loading is performed.
Already interactive compositions consume catalog defaults for command palettes, modals, notifications and transfer lists. Explicit props and configured settings take precedence. Server-safe compositions retain explicit label props. Application content, plural-sensitive business messages and date/number formatting remain the application's locale responsibility.
English, Traditional/Simplified Chinese, Korean and Japanese catalogs are available as optional subpaths. The translations retain their draft status without qualified human linguistic signoff. The pseudo locale is an expansion/encoding fixture, not a reviewed translation. See localization for fallback, ownership and review limits. Direction is an explicit provider setting and does not follow automatically from language.
Tool-neutral design exchange
Default stable token IDs use the product prefix faye-ui:. Callers can supply their own explicit stable ID map; those application-owned identities are preserved and checked on import. @fayegram-ai/faye-ui/devtools/design-exchange exports a versioned local exchange carrying repository authority, source revision, base/payload SHA-256 digests, unique stable token IDs and the full portable theme. Updating an exchange preserves its base. Applying it rejects repository revision conflicts and payload corruption before returning a validated theme.
Digests detect changes; they do not authenticate the author. Review differences before writing source. Metadata/aliases/axes remain in the portable theme; generated CSS is not authoritative. The optional @fayegram-ai/faye-ui/devtools/figma adapter creates a reviewable Figma Variables plan from explicitly selected contexts. Supply actual mode capacity and rem-to-pixel conversion. Numeric lengths/durations and sRGB colors project to native values; other CSS stays exact STRING data with notices. Compatible aliases preserve stable identity. SDK typings are checked against the pinned Figma PluginAPI.
A host can export a plan into a fresh unpublished collection, read a snapshot and import reviewed changes back into the exchange. Export detects name conflicts and rolls back every acquired resource on failure. Snapshot import checks repository revision, contexts, identities, types and alias targets. Account mode limits and portable/metadata bounds apply. Complete end-to-end Figma host validation has not been performed; protocol validation alone does not establish a complete host pass. Ordinary component use does not require a Figma connection.
Reviewed migration
@fayegram-ai/faye-ui/theme/migration accepts documented version-1 partial/full themes plus a supplied current base. Explicit renames update references in base, schemes, densities, axes and conditions. Explicit obsolete-name removals are recorded. Unknown names, collisions, broken aliases and unsupported versions fail.
The result lists added, removed and renamed tokens and contrast findings. Review is always required; filling new tokens is not an accessibility or palette approval. The existing completeTheme API remains available. Keep previous source and paired assets for rollback, and test accepted consumers before replacing deployed assets.