The model · 14 decisions logged

Governance

A design system is only useful while it matches what ships. These are the rules for keeping it in step with gianlucacaico.com, and for changing either one safely.

Who owns what

gianlucacaico.com: The source. Pages, components and artwork are designed and shipped there first.
This design system: The standard. The tokens, components and rules, written down so any page can use them.
Gianluca: Approves every change before it goes live, on either site.
Agent-driven sessions: Draft changes, preview them, open a review page, and check the live site after publishing. They may suggest running an agent, but only Gianluca starts one.

How a change goes live

DraftPreviewReview pageApprovePublishCheck live

Nothing goes live without approval, and approval for one change doesn't carry over to the next.
One change per review page, with the current and proposed wording side by side and phone and desktop previews.
Check the live site after publishing, not just the code.
Every change can be undone by reverting its review page on GitHub.

Skills, harnesses and hooks

Every procedure, automated check and automatic trigger behind both sites, written as tool-agnostic templates.

Open the workflow library

The drift check

The kit is a copy of the site's styles, so a check compares the two and says when they part ways. It runs from both sides, each reading what the other publishes: this design system reads the site's live stylesheet at the end of every preview, and the site reads this design system's tokens in its health check after every publish. Either side can also run it on a change before it merges.

Compares: Every colour, card art and layout token on the site with the kit, plus the colours in the site's artwork template and pictograms.
Drift: A token differs, or exists on only one side. Fix it before publishing, by updating the kit or asking whether the site is right.
Info: A colour is used but isn't a token yet. That's a to-do list for the kit, not a blocker.

Versions

Version 1 only gets changes that can't break a page: new tokens, new components, fixes, and values that follow the site's look.
A breaking change becomes version 2, at its own address, and only with Gianluca's approval. Version 1 then stays as it was.
The unversioned kit is always the latest. Only this site's own pages rely on it.

Proposing a change

Start on the main site if it changes how something looks. The design system follows.
Name new colours and sizes as tokens, each with a plain-English use.
Match the site's class names for new components, and add each one to the demo with placeholder copy.
Run the preview. It has to pass with no drift.
Open a review page and record any design decision in the log below.

Decision log

What has been decided and why, newest first, so nobody has to rediscover it.

14 decisionsLatest: Agents run only when Gianluca starts them. A session may suggest a run, never start one, and Claude Code asks him to approve every launch of the navigation agent.

When	Decision	Why
Nov 2026	Agents run only when Gianluca starts them. A session may suggest a run, never start one, and Claude Code asks him to approve every launch of the navigation agent.	A person stays in the loop: he judges when a sweep is worth running, and nothing runs on a schedule or by itself.
Nov 2026	The design system becomes a portal: a home page that shows every page at a glance, in three groups, and eight short pages instead of one long one. The menu stays on screen, with a Menu button on phones, and every menu, the home page and the footer are built from one list (`_data/nav.yml`).	The single page had reached 34 phone screens and was heading for about 60. People come to look one thing up, and a new page now takes one line to add.
Nov 2026	Pages two levels down show a breadcrumb trail in the glass pill: the same `.crumbs` component on gianlucacaico.com's posts and on this site's Workflows and Kit demo pages.	Readers who land deep from a shared link can see where they are and step up a level, and this site's pages show they belong to gianlucacaico.com.
Nov 2026	Each site's footer links to the other: gianlucacaico.com's footer now links here, and this site's footer links back. This replaces "no links from the main site".	Visitors to either site can find the other, and a footer link doesn't pull attention from the Work page, which was the reason for keeping them apart.
Nov 2026	The docs page opens with the operating model for executives and sponsors, shown through two real changes traced end to end, ahead of Foundations.	Leaders need the outcome and the way of working in under a minute. A real change with its record shows that better than a diagram of the process.
Nov 2026	Every footer carries a small site map. Here: this site's sections, its pages and gianlucacaico.com's main pages. On gianlucacaico.com: its pages, homepage sections and newest posts.	The end of a long page offers a way on without scrolling back up, and both sites use the same pattern.
Nov 2026	The site and the design system check each other: the site reads the design system's tokens, and the design system reads the site's stylesheet.	A difference is caught whichever side changes first, and each report says what the other side needs to do.
Nov 2026	Client names are written as text on project cards, not shown as logos.	There is no formal permission from the clients to show their logos.
Nov 2026	The brighter artwork cyan is its own token, `--cyan-bright` (#12B5CB).	It kept clashing with the site's `--cyan` (#0E97AA) in the artwork template.
Nov 2026	Pictogram highlights use three tints: `--tint-cyan`, `--tint-coral` and `--tint-amber`.	They were already in the site's pictograms but were not tokens anywhere.
Nov 2026	The kit is served as version 1. Breaking changes become version 2, at their own address.	Pages that use the kit should never break without warning.
Nov 2026	A drift check compares the kit with the live site, at the end of every preview.	The kit is a copy of the site's styles, so it has to be told when the site changes.
Nov 2026	The design system lives in its own repo, at gianlucacaico.com/design-system, with no links from the main site.	As a page under Work it distracted from the Work page's purpose, and on its own it can never break the main site.
Nov 2026	The kit's dark surface is derived from ink and the site's on-dark colours.	The main site has no dark mode of its own to copy.