Shared Design System

If the site becomes several sites, they still have to look like members of one family. A visitor who moves from the languages site to the programming site should not feel they have changed websites, and you should not have to change a colour in fifty places. This chapter looks at what the fragments really contain, chooses a design approach that does not require rewriting thousands of files, and sets up the pieces: tokens, shared components, and a safe order for loading them.

What the Fragments Contain Today

Every fragment carries its own <style> block, scoped under its own wrapper class. That scoping rule is deliberate, because it stops one fragment's styles leaking into another. The price is repetition. Measuring a few courses gives these results:

Four findings stand out:

1. The three language courses share the same palette. Surfaces #1a1d27, borders #2a2d3a, text #e2e4ec, muted #a0a4b8 and the purple speaker colour #7c5cbf are identical. Only the accent changes.
2. There are two neutral families. The technical courses use a different set (#161b22 surfaces, #30363d borders, #c9d1d9 text, #8b949e muted), with their own accent per course.
3. The same CSS is copied into every chapter. A colour used nine times in one chapter appears 108 times in a 12-chapter course.
4. CSS is 12% to 32% of each file. A visitor downloads the same styling again on every chapter.

Three Ways to Share Design

This course follows approach C. New content uses the shared layer, and old content keeps its own rules until it is rewritten or migrated by script.

Design Tokens

A token is a named value: --surface instead of #1a1d27. In CSS the natural way to hold tokens is custom properties (variables). They cascade, so you can set a different value for a part of the page, which is exactly what per-language accents need.

Two neutral families can stay as they are for now. Unifying them into one is a design decision for later; tokens make it a small change when you choose to do it, because every use reads the variable.

A safe way to introduce the variable

Existing fragments hard-code their accent. A script can replace each occurrence inside the style block only with var(--accent, #5aa469). The second argument is a fallback: if the variable is not defined, the browser uses the old colour, so the page looks exactly as before. That makes each file's migration independently safe (Exercise 2).

Shared Components

The fragments already use the same class names for the same ideas, which is what makes a shared layer possible:

A shared components.css styles these once, using the tokens. Fragments that still carry their own rules for the same classes keep winning, as the next section explains.

Who Wins When Rules Collide

The existing scoping rule has a useful side effect. A fragment's rule such as .hu-lesson .tip-box is more specific (two classes) than a shared .tip-box (one class), so the fragment's own rule wins. If you write the shared rule with the same specificity, for example [data-site=languages] .tip-box, the two tie, and the later one in the document wins. The layout's stylesheet is in <head> and the fragment's <style> is inside the body, so the fragment still wins. Both effects protect old pages during a migration.

Load order is therefore: tokens, then base, then components, then the fragment's own style. Exercise 3 writes the token file and checks the specificity rules with a small script.

Per-Area Accents

Colour already tells visitors where they are. These accents are in use today, with the contrast each one gives against the language surface #1a1d27:

WCAG level AA asks for a contrast ratio of at least 4.5 for normal-size text. Every accent passes except the Japanese red, at 3.86. It is fine for borders, buttons and large headings, but weak for small coloured text. The right place to fix this is the token file, for instance with a separate lighter --accent-text for that language, not in each chapter (Exercise 3, part D).

Fonts, Printing and PDFs

• Fonts are tokens too. The language lessons use a serif body font (Georgia) and the technical ones use the system sans-serif. Put each in a variable such as --font-body.
• Web fonts and origins. If a font is loaded from another subdomain, the browser requires CORS headers (Learning Website: Framework & Architecture 1). The simplest options are system fonts, or self-hosting the same font files on every site.
• The PDF builders render these same fragments. Any change to the shared layer changes the PDFs too, and the copy buttons are hidden for print by an @media print rule. After a design change, rebuild one chapter PDF and look at it before trusting the change.

Where the Design System Lives

The tokens, base and components are one small unit, shared by every site and versioned together. In a framework this becomes a package or a static folder:

Each site includes the same four files. The Django course (Learning Website with Django 5) serves them as static files, and the Next.js course (Learning Website with Next.js 5) imports them from a shared workspace package. A change in one place reaches every site on its next build, so treat the design system like code: review it and test it before release.

Hands-On Exercises