Spektral treats the component spec as the source of truth. Platform implementations can use their own libraries and idioms, but consumer-visible differences are tracked explicitly.
Read the matrix
- Open the Matrix page
Use the fourth icon in the page switcher at the top of the window. Every component is a row; every platform in your project is a column.
Platforms you have not scaffolded read 'not init'; components with no metadata read 'Unknown'. - Refresh after generating
Press Refresh to re-read every platform's conformance metadata and spec hashes from disk.
- Resolve the Unknowns
Press Record when you already trust the implementation, or Review to have the agent compare it against the spec first. Both are per component, per platform.
Source of Truth
The canonical contract lives in specs/*.spec.yaml: API, variants, behaviour, accessibility, keyboard interactions, and design decisions. React, Vue, Lit, Svelte, and custom platforms are implementations of that contract.
A platform can be a reference implementation for porting, but it is not the authority. The spec and tokens are the authority.
Three Kinds of Difference
| Kind | Meaning | Matrix state |
|---|---|---|
| Implementation detail | The platform uses a library or framework idiom internally, but the public contract still matches the spec. | Synced |
| Platform adaptation | The same concept is expressed in a platform-native way, such as React props versus DOM events. | Synced with an implementation note |
| True deviation | Consumers can observe different API, behaviour, accessibility, or visual semantics compared with the spec. | Deviated |
React Library Example
A React Tooltip might use @floating-ui/react for positioning. That is not a deviation if the Tooltip still follows the shared spec for trigger behaviour, focus handling, collision handling, roles, states, and visual tokens.
{
"component": "Tooltip",
"specHash": "sha256:...",
"status": "conformant",
"implementation": {
"libraries": ["@floating-ui/react"],
"notes": "Used for collision-aware positioning."
},
"deviations": []
}True Deviation Metadata
When a platform intentionally cannot or should not match the spec, record the reason next to the component in .spektral.json. The matrix keeps that visible instead of letting drift hide in code.
{
"component": "Tooltip",
"specHash": "sha256:...",
"status": "deviated",
"implementation": {
"libraries": ["floating-ui"]
},
"deviations": [
{
"type": "api",
"section": "api.props.open",
"reason": "The Lit implementation does not support controlled open state yet.",
"impact": "Consumers cannot externally control open state on Lit.",
"approved": true
}
]
}Matrix States
- Synced: metadata points at the current spec hash and no true deviation is recorded.
- Stale: the shared spec changed after the platform implementation was last recorded.
- Deviated: an approved consumer-visible difference exists and is documented.
- Failing: the implementation targets the spec but validation or audits are known to fail.
- Unknown: the component exists but has no conformance metadata yet.
Updating Existing Projects
Components created before conformance tracking appear as Unknown. Unknown is not a failure; it only means Spektral has not recorded which spec version the platform implementation claims to satisfy.
| Action | Use when | What happens |
|---|---|---|
| Record | You trust the current implementation already matches the current spec. | Spektral writes .spektral.json, stores the current spec hash, and records detected implementation libraries. |
| Review | You want the agent to compare the component against the spec first. | The agent loads the component and spec, then writes conformant metadata or documents approved deviations. |
Migration should not rewrite component code by default. The goal is to make existing parity visible first, then fix or document true differences intentionally.