45out of 100 before any changeLoose threads
133 components and 1301 tokens read.
- Source
- gitlab.com/gitlab-org/gitlab-ui, src (with the package root's docs, tests, stories and token files)
- Pinned at
- v114.1.0 (commit
f8c6c61), @gitlab/ui 114.1.0 - Licence
- MIT: LICENSE (MIT, Copyright GitLab Inc.)
- Why this source
- The GitLab UI repository at its release tag v114.1.0: the Vue components, the DTCG token files, the contribution docs and the tests are all in one public repository, so a clone is the fullest read.
- How it was read
- Git clone of a public repository through Loom's engagement checkout (the same path as the acceptance suite's GitLab check, scripts/acceptance/f1-connect.ts).
- Engine
- Loom conversion engine 0.1.0, commit
1e10804; Loom 2026 standard (public rubric 2026.1); no AI model - Run
- 1 November 2026 with
npm run open-audit -- gitlab-ui --date 2026-11-01
GitLab UI has a strong token foundation and pipeline
GitLab UI's tokens come in three tiers, most semantic and component tokens point at a lower tier, and the tokens are built into code from DTCG source files. Ownership is machine-readable (CODEOWNERS), most components have their own test or story, and CI runs checks. These are the areas where the evidence in the repository is strongest.
The eight areas, with what each score can show
| Area | Score | What the score can and cannot show |
|---|---|---|
| Foundations and tokens | 54 | Scored from what this source holds. |
| Components | 52 | Scored from what this source holds. |
| Patterns and pages | Not scored | No pattern or template records in the inputs: this area is left out of the overall score, not scored zero. |
| Usage | Not scored | Only the library's own source was read: its components defining themselves are not adoption, and usage can only be measured in product code that consumes the library, so this area is left out of the overall score. |
| Governance | 42 | Decision records and a lifecycle per component were not found in this repository. GitLab keeps much of its design guidance in Pajamas, its design system site, which lives in another repository and was not read. |
| Brand, illustration, microcopy and localisation | 35 | Scored from what this source holds. |
| Tools and sync | 69 | GitLab UI publishes its documentation through Storybook. The rubric's documentation-site check looks for a site built from the system's records, so the Storybook documentation scores as a workshop (stories), not as a documentation site. |
| AI readiness | 17 | Scored from what this source holds. |
Three findings, with their evidence
Each finding links to the file at the pinned commit, or says that nothing was found in the source we read.
105 role tokens duplicate another token's literal colour
Role tokens that copy a primitive's value instead of pointing at it drift apart when the palette changes.
Evidence
- illustration.stroke.color.default #171321 = color.brand-charcoal — gitlab-ui/src/tokens/contextual/illustration.tokens.json:5 (dtcg)
- illustration.fill.color.default #ffffff = color.neutral.0 — gitlab-ui/src/tokens/contextual/illustration.tokens.json:27 (dtcg)
- illustration.status.fill.color.neutral #aea5d6 = illustration.accent.stroke.color.strong — gitlab-ui/src/tokens/contextual/illustration.tokens.json:40 (dtcg)
Loom's proposed change
Replace each duplicate with an alias ({palette.x}); two literals with the same value drift apart on the first edit.
Required modes missing: high contrast
Light and dark are declared as token modes; high contrast is not, and nothing records a decision either way.
Evidence
- light: token mode "default"
- dark: token mode "dark"
- high contrast: silent
Loom's proposed change
Declare light, dark and high-contrast as token modes that remap semantic aliases, and contrast-check every pair in every mode. A recorded 'not supported' decision is honest but does not meet the 2026 baseline.
No machine-readable component contracts
AI readiness is the lowest area: agents have to infer each component's rules from source and prose.
Evidence
- Not found anywhere in the source we read.
Loom's proposed change
Publish contracts as JSON (generated stubs in artefacts/contracts) so agents read rules instead of inferring them from source.
Every gap, and what Loom would propose
| Area | Gap, and what the source showed | What Loom would propose |
|---|---|---|
| Foundations and tokens | DTCG token file validates265/1043 valid in gitlab-ui/src/tokens (39 DTCG files); 265 alias references | Adopt the typed token set (typed, described, DTCG-valid) and build it with the token pipeline. |
| No role token repeats another token's literal105 duplicates among 128 non-primitive literal colours (×5 penalty) | Adopt the typed token set (typed, described, DTCG-valid) and build it with the token pipeline. | |
| Colour pairs meet WCAG in every declared mode448/1344 pairs pass; checked in 1 of 2 declared mode(s); 0 name-based pairs listed separately; 65 undeterminable | Adopt the typed token set (typed, described, DTCG-valid) and build it with the token pipeline. | |
| OKLCH or declared colour spacecolour values with no declared space | Adopt the typed token set (typed, described, DTCG-valid) and build it with the token pipeline. | |
| Consistent naming (shared prefix, kebab-case)11% share the dominant prefix; 260/1301 kebab-case | Adopt the typed token set (typed, described, DTCG-valid) and build it with the token pipeline. | |
| Components | Average contract completeness (10 template fields)23% across 133 components | Fill the open contract fields (the questions are in each contract). |
| Components at ≥80% completeness0/133 | Fill the open contract fields (the questions are in each contract). | |
| Matching keyboard/focus test source in supplied inputs15/49 components identified as interactive by name or export; source matches only, execution not assessed; roots: gitlab-ui | Fill each contract's behaviour and accessibility fields, and test the states in stories with the interaction and a11y add-ons. | |
| Cross-platform parity (React Native counterpart or explicit exclusion)0/133 with a counterpart or platform declaration | Fill the open contract fields (the questions are in each contract). | |
| Governance | Changelogdocumented: A product changelog exists but it does not track UI components or tokens. | Answer the setup questions (npm run setup, or Setup in the control area): they write loom/governance.json, rituals and monitoring; the plan's governance model is the proposal they start from. |
| Deprecation policy with timelinesmentioned: Deprecation is mentioned without a policy (replacement, removal condition, timeline). | Answer the setup questions (npm run setup, or Setup in the control area): they write loom/governance.json, rituals and monitoring; the plan's governance model is the proposal they start from. | |
| Decision recordsabsent: No decision records found. | Answer the setup questions (npm run setup, or Setup in the control area): they write loom/governance.json, rituals and monitoring; the plan's governance model is the proposal they start from. | |
| Layer model (system of systems)absent: No layer model: a single layer, with nothing that says what a brand, region or product may override. | Answer the setup questions (npm run setup, or Setup in the control area): they write loom/governance.json, rituals and monitoring; the plan's governance model is the proposal they start from. | |
| Lifecycle statusabsent: 133 components have no lifecycle status. | Answer the setup questions (npm run setup, or Setup in the control area): they write loom/governance.json, rituals and monitoring; the plan's governance model is the proposal they start from. | |
| Brand, illustration, microcopy and localisation | Brand rulesmentioned: Mentioned in passing (2 places); no rule an agent or reviewer could check work against. | Fill the guideline's decisions and turn them into rules Loom checks. |
| Message catalogue (IDs + variables)absent: No message catalogue: UI strings are literals in code (or English defaults in props), with no IDs, variables or plural rules a writer, translator or copy check can work from. | Fill the guideline's decisions and turn them into rules Loom checks. | |
| Localization policydocumented: Prose guidance only; nothing machine-readable, so it cannot be enforced or handed to an agent as rules. | Fill the guideline's decisions and turn them into rules Loom checks. | |
| Localisation readinessabsent: Signals found: none; missing: externalised strings, pseudo-localisation, text-expansion rule, direction (RTL) rule. | Fill the guideline's decisions and turn them into rules Loom checks. | |
| Tools and sync | Documentation site built from the system0 documentation pages; gitlab-ui/README.md | Use Storybook autodocs as the documentation site built from the system. |
| Design tool linked to codenone found | Map each component to its Figma component (Code Connect). | |
| AI readiness | Components with a machine-readable contract0/133 | Adopt the machine-readable contracts and their exact imports. |
| Components with followable rules (do/don't/when-not)42/133 | Ship the agent rules and instructions (and connect Loom's MCP server for live lookups). | |
| MCP/knowledge interfaceno MCP; no static index | Ship the agent rules and instructions (and connect Loom's MCP server for live lookups). | |
| Retrieval tests shipped with the systemnone found | Ship the retrieval tests and run them in CI. | |
| Builder knowledge index returns the right component + import0/0 top-1 hits with import | Ship the retrieval tests and run them in CI. | |
| Agent instructions shipped with the systemnone found | Ship the agent rules and instructions (and connect Loom's MCP server for live lookups). | |
| Tokens with allowed/forbidden use1/1301 | Ship the agent rules and instructions (and connect Loom's MCP server for live lookups). |
The proposed after: draft pull requests, never opened
A dry run: 6 draft pull requests were planned and none was opened. Nothing was applied to GitLab UI.
- Token set: typed, aliased and valid DTCG, built from one source
loom/plan/gitlab-ui-tokens-89bdef6534 - A contract per component: purpose, when to use and not, states, accessibility, content
loom/plan/gitlab-ui-contracts-b593236c7a - Governance records: changelog, deprecation policy, decisions, layers, lifecycle
loom/plan/gitlab-ui-governance-3319f13f89 - Guidelines as rules: brand, voice, message catalogue, localisation
loom/plan/gitlab-ui-guidelines-8f4372ad61 - Agent interface: instructions, rules and retrieval tests
loom/plan/gitlab-ui-agent-458bb40a61 - Tools: stories, keyboard tests and a documentation site
loom/plan/gitlab-ui-tools-448b523574
What this read cannot show
- Static analysis only: no code was run, no build was made and no test was executed. A matching test file is evidence that the test exists, not that it passes.
- Usage is not scored. Only the library's own source was read; usage can be measured only in the product code that consumes the library, which is not part of this source.
- A low area can mean the evidence is not in the public source we read (it may live on a documentation site, in another repository or in a team process), not that the system is weak there.
- Patterns and pages are not scored: the source holds no pattern or page-template records Loom can read, so the area is left out of the overall score.
- Nothing was applied to the project. The plan is listed as draft pull requests that were not opened (a dry run), and no after score is claimed.
- Read from the repository at tag v114.1.0 only. Pajamas, GitLab's design system site and guidelines, lives in another repository and was not read.
- Contrast is checked on the values one mode resolves to, using name-based pairs where no pairing is declared; name-based pairs are possible combinations, not confirmed ones.