learning-website-framework1-4  Exercise 3: Tokens, Specificity and Load Order
===================================================================================

PART A: Write tokens.css for the two neutral families
-----------------------------------------------------
Values come from the real palettes found in Exercise 1.

/* tokens.css — loaded by the shared layout on every site */
:root {
  /* language-course family */
  --lang-bg:       #0f1117;
  --lang-surface:  #1a1d27;
  --lang-border:   #2a2d3a;
  --lang-text:     #e2e4ec;
  --lang-muted:    #a0a4b8;

  /* technical-course family */
  --tech-bg:       #0f1117;
  --tech-surface:  #161b22;
  --tech-border:   #30363d;
  --tech-text:     #c9d1d9;
  --tech-muted:    #8b949e;
}

/* the family a site uses is chosen once, on the page wrapper */
[data-family="language"] {
  --bg: var(--lang-bg);  --surface: var(--lang-surface);  --border: var(--lang-border);
  --text: var(--lang-text);  --muted: var(--lang-muted);
}
[data-family="technical"] {
  --bg: var(--tech-bg);  --surface: var(--tech-surface);  --border: var(--tech-border);
  --text: var(--tech-text);  --muted: var(--tech-muted);
}

/* accents are per language / per site */
.hu-lesson { --accent: #5aa469; }   /* Hungarian */
.de-lesson { --accent: #e0a82e; }   /* German */
.jp-lesson { --accent: #d64550; }   /* Japanese */
.fr-lesson { --accent: #4f8ef7; }   /* French */

PART B: Who wins when shared and fragment CSS collide?
------------------------------------------------------
Save as specificity.py:

import re

def specificity(selector):
    """(ids, classes/attributes/pseudo-classes, elements) for a simple selector."""
    s = re.sub(r"::?[a-z-]+\([^)]*\)", "", selector)      # drop :not(...) style args for this simple version
    ids = len(re.findall(r"#[\w-]+", s))
    classes = len(re.findall(r"\.[\w-]+|\[[^\]]+\]|:[a-z-]+", s))
    s2 = re.sub(r"#[\w-]+|\.[\w-]+|\[[^\]]+\]|::?[a-z-]+", " ", s)
    elements = len([t for t in re.split(r"[\s>+~]+", s2) if re.match(r"^[a-zA-Z]", t)])
    return (ids, classes, elements)

rules = [
    ".tip-box",
    ".lwf1-lesson .tip-box",
    ".hu-lesson .tip-box",
    "[data-site=languages] .tip-box",
    "div.tip-box",
    "#content .tip-box",
]
for r in rules:
    print(f"{str(specificity(r)):<12} {r}")
print()
a, b = ".tip-box", ".hu-lesson .tip-box"
print(f"{b!r} beats {a!r}: {specificity(b) > specificity(a)}")
print(f"tie between '.hu-lesson .tip-box' and '[data-site=languages] .tip-box': "
      f"{specificity('.hu-lesson .tip-box') == specificity('[data-site=languages] .tip-box')}")

Output (checked by running it):

(0, 1, 0)    .tip-box
(0, 2, 0)    .lwf1-lesson .tip-box
(0, 2, 0)    .hu-lesson .tip-box
(0, 2, 0)    [data-site=languages] .tip-box
(0, 1, 1)    div.tip-box
(1, 1, 0)    #content .tip-box

'.hu-lesson .tip-box' beats '.tip-box': True
tie between '.hu-lesson .tip-box' and '[data-site=languages] .tip-box': True

(This calculator is deliberately simple: it ignores :not(), :is() and
:where(). Browsers use the full rules.)

Reading the result
------------------
- A fragment's own rule ".hu-lesson .tip-box" has higher specificity than a
  shared ".tip-box", so the fragment wins. That is the safe default during
  migration: old pages keep their look until you remove their rules.
- A shared rule written as "[data-site=languages] .tip-box" TIES with the
  fragment's rule. On a tie, whichever comes LATER in the document wins. The
  layout's stylesheet link is in <head>; the fragment's <style> is inside
  <body>, so the fragment still wins.
- Never solve a clash with !important. It spreads, and it makes the next change
  harder.

PART C: Load order for the shared layout
----------------------------------------
1. tokens.css (variables only, no visible rules)
2. base.css (page, typography, links)
3. components.css (.tip-box, .code-block, .compare-table, ... with variables)
4. The fragment, with its own <style> (wins ties, so old pages are unchanged)

PART D: Check the accents are readable
--------------------------------------
Before an accent becomes a token it should be readable on the surface it sits
on. Save as contrast.py (the WCAG contrast-ratio formula):

def lum(h):
    h = h.lstrip("#")
    r, g, b = (int(h[i:i+2], 16) / 255 for i in (0, 2, 4))
    f = lambda c: c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
    return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b)

def ratio(a, b):
    la, lb = sorted((lum(a), lum(b)), reverse=True)
    return (la + 0.05) / (lb + 0.05)

BG = "#1a1d27"
accents = {"Hungarian": "#5aa469", "German": "#e0a82e", "Japanese": "#d64550",
           "French": "#4f8ef7", "Links": "#38bdf8", "Sidebar lesson": "#fbbf24",
           "Cheat sheet": "#6ee7b7", "Framework course": "#5eead4"}
print(f"Contrast ratio against {BG} (WCAG AA needs 4.5 for normal text):")
for name, c in accents.items():
    r = ratio(c, BG)
    print(f"  {name:<18} {c}  {r:5.2f}  {'pass' if r >= 4.5 else 'FAIL'}")

Output (checked by running it):

Contrast ratio against #1a1d27 (WCAG AA needs 4.5 for normal text):
  Hungarian          #5aa469   5.56  pass
  German             #e0a82e   7.85  pass
  Japanese           #d64550   3.86  FAIL
  French             #4f8ef7   5.24  pass
  Links              #38bdf8   7.85  pass
  Sidebar lesson     #fbbf24  10.07  pass
  Cheat sheet        #6ee7b7  11.03  pass
  Framework course   #5eead4  11.37  pass

Finding: the Japanese red (#d64550) comes out at 3.86, below the 4.5 that WCAG
AA asks for normal-size text, while every other accent passes. It is fine for
large headings and borders but weak for small coloured text. Options: keep it
for borders, buttons and large headings only; or define a lighter text variant
(for example --accent-text) just for that language. Decide once, in the tokens
file, not in each fragment.

WHY THIS WORKS AS AN ANSWER
---------------------------
The tokens file is the only place a colour is decided; everything else
refers to it by name. The specificity check explains why a migration can be
done gradually: old fragment rules keep winning until you delete them, and the
shared layer only supplies the defaults for new content.