The Shared Design System

Eight sites should look like one family, and each should be recognisable at a glance. This chapter moves the Django project's theme into a package, @lw/ui, that every app imports: one set of stylesheets, a frame component, and a colour for each site. It answers one real question about Next.js (CSS Modules or global CSS?) and then measures whether the result looks the same as the Django site, instead of saying so.

Tokens: the One Place a Colour Is Decided

tokens.css holds every colour as a variable, and nothing else in the design writes a colour of its own. It is the Django project's file unchanged. Two neutral families exist (a warmer one for the language courses, a cooler one for the technical courses), and each site has one accent. The accent is a CSS variable on the <html> element, so one stylesheet serves every site and only that value differs:

Rules That Are Tests

• Every site has a style, and its own accent.
• Every accent is readable as text on both neutral surfaces: a contrast of at least 4.5 (WCAG level AA). The test reads the real colours out of tokens.css instead of copying them into the test, so changing a token changes what the test sees. The contrast function itself is checked against known values (black on white is exactly 21; #777777 on white is 4.48, the famous “just fails”).
• No !important in any shared stylesheet.
• Shared component rules stay weaker than a fragment's own (no ids, at most two parts), explained below.

CSS Modules or Global CSS?

CSS Modules rename every class to something unique, so one can never clash with another. That is exactly right for the site's own parts and exactly wrong for the classes the lesson fragments use. A fragment is a file of HTML written long ago, and it says class="tip-box". If tip-box were a module class, the stylesheet would hold a renamed class and the fragment would match nothing. So the choice follows from one fact: who writes the class name.

The built output shows the difference:

A fragment also brings its own scoped <style> (for example .hu-lesson .tip-box { ... }). The shared rules use a single class, so the fragment's rule is more specific and wins. That is deliberate: an old page keeps its look. A test reads components.css and fails if any selector has an id or more than two parts.

Does It Look the Same as the Django Site?

Both were started, and a real headless Chrome, driven through the DevTools protocol, opened the same Hungarian lesson on each and read the computed style of 27 properties: the accent variable, the body, the main column, the page title, a tip box, a dialog card, a vocabulary table, a speaker label.

A style guide page (/styleguide, in both apps) shows every shared building block at once. Looked at by eye: the Languages site is purple on the warmer neutral surface, the Web Development site is sky blue on the cooler one, and the warning and finding boxes keep their own colours on both.

Hands-On Exercises