From a colour library
to a system with intent.

A library can look complete and still leave decisions unresolved.

The starting point was a UI library with colour primitives and semantic roles for light and dark themes. Its visible structure suggested a reusable foundation. My task was to look beneath that structure: were the tones meaningfully differentiated, did named colour relationships remain readable, and could teams apply them without repeatedly making their own interpretations?

I treated the audit as a systems problem. An individual colour can be visually appealing while being unsuitable for a particular text or background role. A semantic name can sound clear while leaving its intended foreground undefined. Those gaps matter because they can be repeated wherever the library is reused.

I focused this assessment on the colour foundation and its relationship to components. I did not treat a colour review as proof that the whole product was accessible. Typography, keyboard behaviour, assistive technology support and interaction-level evaluation would require their own checks.

I examined the foundation, the relationships and the rules.

I organised the work around three connected layers. First, I reviewed the primitive ramps to understand their lightness progression and adjacent perceptual differences. Then I examined foreground/background combinations in each theme. Finally, I considered whether the token architecture could communicate intended use and support future changes.

This sequence kept the recommendations connected. Rebuilding a ramp creates more usable colour choices, but those choices still need explicit semantic assignments. Likewise, renaming tokens cannot repair a pairing whose contrast remains insufficient.

Same identity.
More useful tonal choices.

The original blue ramp moved from light to dark, but the distance between tones was uneven. I retained its anchor colour and redistributed the surrounding tones to give semantic roles a more predictable foundation.

Orange needed more flexibility at the light end.

The revised lightest orange provides a subtler surface option. Its reported lightness rises from 91.22 to 96.02, while the central orange remains unchanged.

A shared foundation across semantic colours.

Red, green, yellow and violet extend to nine tones each. Lighter and darker options give teams more scope to define surfaces, content and states without inventing extra colours.

Swatches reproduce the original and revised hex values shown in the audit. Tone numbers are positions within each scale; matching numbers do not guarantee equivalent lightness across colour families.

The more consequential gaps were between colours.

Base neutral surface pairings met the audit’s AA checks, but positive, negative and link text did not perform consistently across the two surfaces and themes. This demonstrated why checking a colour in isolation was insufficient. The same foreground could work against one background and fail against another.

For example, positive text on the first light surface was reported at 3.19:1, while the proposed pairing reached 7.36:1. On the second light surface, link text moved from a reported 3.13:1 to 6.48:1. These were targeted pairing changes, not evidence that every combination in the library had passed.

Missing pairings were a documentation problem as well as a colour problem.

The container review exposed three distinct situations: defined pairings that could be tested, container roles without an explicit foreground counterpart, and foreground tokens without a corresponding container. I separated these categories because they require different fixes. A failing pair needs colour adjustment; an undefined relationship first needs an intended-use decision.

One light-theme negative pairing used the same colour for foreground and background, producing a reported ratio of 1.00:1. Other secondary and positive pairings also failed the audit’s checks. In the dark theme, several existing combinations remained difficult to distinguish. I proposed explicit pairings for primary and secondary actions, information, positive and negative roles, including interaction-state variations.

The recommendation was to preserve proximity to the existing palette where possible while choosing combinations that supported the intended role. The goal was a usable relationship between colours, rather than unnecessary extremes at either end of a ramp.

I separated immediate alignment from the longer-term architecture.

The deliverables followed two levels of semantic maturity. The first retained the supplied structure so the improvements could remain recognisable. The second proposed a clearer extension for borders, interaction states and accessibility-driven roles. Keeping these levels separate made the difference between a requirement-aligned revision and a future evolution explicit.

This distinction is central to how I approach Design Systems. A semantic token describes purpose. Its underlying value may change by theme, but the component should retain a stable reference to that purpose. When components bypass the semantic layer and use raw palette values directly, every later theme or contrast adjustment becomes harder to manage.

In a design library, this structure also supports review. A reviewer can ask whether a component references the correct role, whether its matching foreground exists, and whether that relationship is supported in each theme. Those questions are more actionable than asking whether a chosen colour simply looks right.

The validation result was strong, but it was not complete.

The assessment recorded 97 passing combinations out of 104 tested across contrast, theme consistency and UI states. That is a calculated pass rate of 93.3%, with seven combinations not passing. I would keep those remaining cases visible rather than describe the system as fully accessible.

The surface and container evidence shows where specific pairings improved, while the aggregate result gives a broader view of validation coverage. Those are complementary forms of evidence. Neither establishes how the library performed after implementation or how users experienced the final product.

Before release, the next step would be to identify the seven outstanding combinations, resolve or document each case, and repeat the relevant checks in actual components. That follow-through matters because a token can be valid in one documented pairing and be applied incorrectly elsewhere.

A clearer library also needs a clear way to maintain it.

The audit defined semantic-first usage: components should reference semantic tokens rather than primitives. I would operationalise that principle through a small set of review expectations, making it easier to recognise acceptable use and to assess additions consistently.

These are the implementation and maintenance steps I recommend from the findings. The assessment demonstrates the audit and proposed system direction; it does not establish that a team adopted these processes or completed a production migration.

What this work demonstrates about my approach.

This assessment shows how I connect visual craft with measurable evidence and system structure. I moved from identifying irregular tonal spacing to reviewing semantic relationships, then shaped the findings into a clearer architecture for two themes. The work made the reasoning behind the changes visible, rather than presenting a revised palette without explanation.

The most important lesson was that a Design System is not simply a collection of well-arranged assets. Its value depends on the relationships and rules that help other people use those assets correctly. Colour foundations, paired semantic roles and component references need to work together.

The resulting assessment offers a concrete basis for the next conversation: which changes can be adopted within the existing structure, which need broader architecture agreement, and what must be validated before implementation. It is a foundation for informed delivery decisions, with the remaining work clearly identified.

Source: my Design Library Audit assessment, pages 2–9. Figures are reported measurements or explicitly labelled calculations. Client identity is omitted. Proposed architecture and pairings are presented as assessment outputs, not verified production outcomes.