Diego Souza · AI Engineer

All projects

This site and its design system

A design system with contrast checked by tests, and a site that refuses unproven numbers.

local gates pass, not published yetLast verified: 2026-10-31 · Commit 83c2253

TL;DR

Problem
A portfolio makes claims. Without a rule that ties each number to a saved run, it drifts toward marketing.
My role
I designed the system, the components, the evidence pipeline and the pages.
Stack
React, TypeScript, Vite, Three.js, ELK (build time), Playwright, axe, Cloudflare Pages
Result
Contrast is checked by axe in real Chrome in both themes, at a wide and a narrow viewport. The checks are in the repository, not in this sentence.

`colagem-ui` is my own React design system: tokens, components and a contrast table verified in code and in a real browser. This portfolio is built on it, and its build fails when a project number has no evidence behind it.

See it run

The live demo runs this system against a real model and shows every step.

Live demo

How it works

From a project's evidence to a number on this pageFlow: Evidence file, Evidence generator, Evidence record, Number rule, Number on the pageEvidence fileEvidence generatorEvidence recordNumber ruleNumber on the pageFrom a project's evidence to a number on this pageFlow: Evidence file, Evidence generator, Evidence record, Number rule, Number on the pageEvidence fileEvidence generatorEvidence recordNumber ruleNumber on the page

The whole flow. Press play or next to walk through it.

Text version of this diagram
  1. Evidence file P07. A report or a test run saved in a project repository.
    • then Evidence generator
  2. Evidence generator P07. Reads the file at its last commit and copies the value exactly.
    • then Evidence record
  3. Evidence record P07. Value, mode, command, exit code, commit and path.
    • then Number rule
  4. Number rule P07. A test fails on a digit that has no record behind it.
    • then Number on the page
  5. Number on the page P07. The page shows the value with a link to the exact commit.

Decisions

A number needs a record

Evidence records are generated from files in the project repositories at an exact commit. A test fails on a digit in case text that has no record.

Code: scripts/evidence.mjs

Rejected: Typing numbers into the page by hand.

Diagrams are laid out at build time

ELK computes the layout during the build, and React draws SVG from the result. No layout engine reaches the browser.

Code: scripts/flows.mjs

Rejected: Mermaid, D2 and React Flow in the browser, which I measured under this site's CSP.

Results

Measured

PENDING

Not measured, so not claimed

  • Real-user performance. No traffic yet.
  • Frame rate of the 3D scene on an entry-level phone. It is pending a device test.

Failure gallery

What happened
Real Chrome found contrast defects that unit tests could not see.
Cause
jsdom does not compute contrast. Links and panels designed for the dark theme ended up on dark surfaces in the light theme.
What changed
The fixes are in the component CSS, and the browser test stays in the gate.
What happened
Wrapped diagram labels failed an accessibility rule.
Cause
Line breaks in SVG text dropped the spaces, so the visible name no longer matched the accessible name.
What changed
Each wrapped line carries its trailing space.

Validate it yourself

git clone https://github.com/DiegoVSouza/diego-portfolio-ai.git
cd diego-portfolio-ai
npm ci && python scripts/check_fast.py

Expected: Lint, types, the evidence, flow and catalog checks, and the unit tests pass.

What I would do differently

I would have written the evidence pipeline before the first page, so no draft ever held a typed number.

Next project

The engineering harness