03 · Light Theme · decision tree + override patterns¶
Зачем этот файл¶
Light theme v2 (canonical 2026-05-03) — premium senior дизайн с 4 уровнями контраста, bronze CTAs и контекстно-зависимым footer (Stripe-pattern dark для marketing, cream для UI-app). Это НЕ простая инверсия dark theme.
Самые частые ошибки:
- White-on-white text (hardcoded rgba(255,255,255,X) color в class definition)
- Stripe-dark footer на academy UI-app (правильно — на marketing)
- Premium PDF artifact «immutable dark» в light theme (CEO 5x жаловался про сертификат)
- Hover state с только color, без bg → bg остался white из idle → text invisible
Этот файл — decision tree «что делать с элементом X в light theme» + override patterns + полный список anti-patterns.
Decision tree · что делать с элементом¶
Алгоритм 7 шагов. Применяется к КАЖДОМУ элементу при создании / правке экрана.
Шаг 1 · Brand-immutable?¶
Вопрос: этот элемент — header / cube / wordmark / brand cap?
Если ДА:
- Background ОСТАВИТЬ dark (rgba(18,18,22,0.88) для header)
- Text ОСТАВИТЬ white (override через [data-theme="light"] .eco-header * rule в master CSS line 320+)
- Не пытаться адаптировать на light
Эталон: header на любом из 36 экранов в light theme.
Шаг 2 · Footer?¶
Вопрос: это <footer class="eco-footer">?
Если ДА — определить контекст:
- Marketing/landing (.ai/.com/.org/syndicate marketing pages, checkout marketing) → Stripe-pattern dark #0E0D0B + WHITE text + #181614 triad tiles
- UI-app (academy / gate-admin / syndicate-app) → cream var(--bg-secondary) + DARK text + bronze accents
Реализация UI-app:
- Page-isolated <style> блок с !important (потому что master имеет dark default с !important)
- См. реальный пример в ecosystem-prototype/academy/courses.html после v4.4.17
Шаг 3 · Card / surface?¶
Вопрос: это card / panel / surface element?
Если ДА:
- Background #FFFFFF (pure white)
- Border var(--border-default-light) (rgba(26,26,26,0.12))
- Shadow var(--shadow-card-light) (layered subtle)
- Hover shadow boost var(--shadow-hover-light)
Anti-pattern: не использовать var(--bg-secondary) (cream) для card на cream body — card исчезает визуально.
Шаг 4 · Body / card text?¶
Вопрос: это primary text в body или внутри card?
Если ДА:
- Color #0A0A0A (deep type)
- НЕ pure black #000000
- НЕ #1A1A1A (мутно)
- Через var(--text-primary) token
Шаг 5 · CTA?¶
Вопрос: это action button (primary / secondary)?
Если ДА:
- Color / border #998018 (deep bronze)
- НЕ #EBC554 (яркий gold для dark theme)
- На hover: solid bronze bg + WHITE text
- Через var(--cta-primary) / var(--accent-amber-dark) token
Шаг 6 · Status indicator?¶
Вопрос: это status chip / badge / pill (success / error / warning)?
Если ДА:
- Сохранить semantic colors (green = success, red = error, amber = warning)
- НО на light theme использовать deeper variant для контраста на белом:
- Green: #16A34A (вместо #22C55E)
- Red: #B22222 (вместо #EF4444)
- Amber: #998018 (вместо #EBC554)
- Cyan: #0891B2 (вместо #00F0FF)
- Background — light tint (10-20% opacity)
- Border — medium tint (30-50% opacity)
Шаг 7 · Premium artifact?¶
Вопрос: это certificate / OG-image / PDF / share-image?
Если ДА:
- В light theme — light surface (cream/white) как настоящая бумага
- Gold details PRESERVE (cube / cert-name foil / corners / dividers / brackets) — independent of theme
- Toolbar (если есть) — реактивный к theme через --header-bg token (дает dark в dark, cream в light)
- НЕ «immutable dark» (это была anti-pattern до v4.4.17)
Эталон: certificate.html после v4.4.17 fix.
Immutable vs Reactive matrix¶
Ключевая таблица для override decisions. Без неё легко ошибиться «что должно реагировать, что нет».
| Элемент | Dark theme | Light theme | Override location |
|---|---|---|---|
.eco-header bg |
dark rgba(18,18,22,0.88) |
dark (immutable) | Master CSS implicit |
.eco-header * text |
white | WHITE override | Master CSS line 320+ |
.eco-cube (logo) |
gold | gold (immutable) | None — drop-shadow same |
.eco-wordmark .gold |
#EBC554 |
#EBC554 |
None |
.eco-wordmark .br (header) |
white | WHITE | Master CSS |
body bg |
#080808 |
#FAFAF7 cream |
Token via --bg-secondary |
body text |
white | #0A0A0A |
Token via --text-primary |
body font-weight |
400 |
500 (Apple/Stripe принцип) |
Master CSS |
.btn-action bg |
#EBC554 |
#998018 |
Master CSS |
.btn-ai-primary:hover |
gold + dark | gold + WHITE | Master CSS line 488-489 |
.btn-ai-success:hover |
green + dark | green + WHITE (!important) |
Master CSS line 357-358 |
.btn-ai-vip:hover |
purple + dark | purple + WHITE (!important) |
Master CSS line 360-361 |
.btn-ai-investor:hover |
steel + dark | steel + WHITE (!important) |
Master CSS line 363-364 |
.eco-footer (marketing) |
dark | dark #0E0D0B Stripe (!important) |
Master CSS line 320-351 |
.eco-footer (academy/UI-app) |
dark | cream var(--bg-secondary) |
Page-isolated с !important |
.cert-paper |
dark gradient | white gradient (!important) |
Master CSS line 265-285 |
.cert-paper text (course/issued/labels) |
white | dark #0A0A0A |
Master CSS |
.cert-paper gold details (cube/foil/corners) |
gold | gold (immutable) | None |
.cert-toolbar bg |
dark | cream | Token via --header-bg |
.course-card-locked .course-thumb::before (chip) idle |
gold-on-dark | bronze on white (!important) |
Master CSS line 1929 |
.course-card-locked:hover .course-thumb::before (chip) |
bronze fill + dark text | tier-color fill + WHITE text + glow (!important) |
Master CSS line 1930 (v4.4.17) |
.eco-status-chip (green active) |
green-on-dark | #16A34A deeper green |
Master CSS |
.tier-pill-l1 (status) |
green tint | #16A34A darker |
Master CSS |
Override patterns · master vs page-isolated¶
Master CSS (eco-components.css)¶
Когда использовать: - Правило затрагивает 5+ экранов одного типа - Это canonical pattern (footer dark / cert paper light / chip hover) - Migration существующего class behaviour (token rename)
Where: ui-kit/eco-components.css master file (~2070 строк).
Sections для light theme: - Lines ~110-260 · canonical light theme tokens block - Lines 261-303 · cert-paper / cert-toolbar overrides - Lines 305-318 · body min-height fix - Lines 320-351 · marketing footer Stripe-pattern dark - Lines 353-366 · btn hover overrides (success/vip/investor/action) - Lines 480-490 · btn-ai base hover на light - Lines 1928-1930 · course-card-locked chip overrides - Lines 1540-1900 · canonical v2 main block (premium senior) - Lines 2046-2057 · btn-ai-primary deep bronze override
Page-isolated <style> (HTML inline)¶
Когда использовать: - Правило для ОДНОГО конкретного экрана - Уникальный layout / context (cert toolbar special / investor portal restructure) - Override master rule для одной страницы (academy footer light vs marketing footer dark)
Where: <head><style> блок в самом HTML.
Naming convention:
- В комментарии указать v4.X.Y · CEO YYYY-MM-DD для traceability
- Префикс selector через [data-theme="light"] для специфики
- Если перебивает master с !important — обязательно !important
!important rules¶
Когда обязателен:
1. Page-isolated rule перебивает master rule с !important (война !important-ов выигрывает поздний source — page после master link в <head>)
2. Override theme-reactive token (нужно перебить --bg-secondary для конкретного класса в специфическом контексте)
3. Visual fix критический (white-on-white текст невидим)
4. Master rule для overall theme switch (footer dark Stripe, cert paper light)
Когда НЕ нужен:
- Page-isolated добавляет новый класс отсутствующий в master
- Specificity boost через [data-theme="light"] body .X достаточен (specificity 0,3,0 vs 0,2,0)
- Уверенность что cascade order сработает естественно
Anti-pattern: !important на ВСЕХ rules «just in case» — превращает CSS в !important war zone. Использовать только когда нужно.
Reading order для override decisions¶
Когда видишь баг визуальный в light theme:
1. Открой DevTools → Computed → проверь конечное значение свойства
2. Найди какое rule выиграло (Sources / Style panel)
3. Если rule в master — посмотри есть ли page-isolated override
4. Если нужно перебить master — page-isolated с !important
5. Если затрагивает все экраны типа — fix в master
Для сложных случаев — getMatchedCSSRules() или JS-анализ stylesheets:
let arr=[];
for(let i=0;i<document.styleSheets.length;i++){
const sh=document.styleSheets[i];
try{
const rules=sh.cssRules;
for(let j=0;j<rules.length;j++){
const r=rules[j];
const sel=r.selectorText||'';
if(sel.indexOf('CLASSNAME')>=0){
arr.push({i, sel, css:r.cssText.slice(0,120)});
}
}
}catch(e){}
}
Anti-patterns light theme · 10 правил¶
Каждое — выученный урок (CEO ловил визуально, переделывали).
1 · color: rgba(255,255,255,X) в class definitions¶
❌ Wrong:
.my-text { color: rgba(255,255,255,0.65); }
✅ Right:
.my-text { color: var(--text-muted); } /* token reagирует */
Или page-isolated override:
[data-theme="light"] .my-text { color: rgba(10,10,10,0.55) !important; }
2 · background: var(--bg-secondary) без проверки¶
❌ Если cream-on-cream — card исчезает.
✅ Проверь computed bg родителя. Если родитель уже --bg-secondary, card должна быть --bg-primary (#FFFFFF) для contrast.
3 · Inline <style> [data-theme="light"] блоки в новых экранах¶
❌ Создавать новый page-isolated theme block без проверки master — дублирование, потенциальный конфликт.
✅ Сначала grep master CSS на existing rule. Если есть — расширить master или использовать. Если нет — page-isolated с явным комментарием почему.
4 · #EBC554 яркое gold для CTAs в light¶
❌ Слабый контраст на cream.
✅ #998018 deep bronze.
5 · Pure white #FFFFFF body bg¶
❌ Слишком резко глазу.
✅ #FAFAF7 warm bone.
6 · Stripe-pattern dark footer в академии (UI-app)¶
❌ Anti-pattern — UI-app context требует cream.
✅ Marketing — да (canonical), academy/gate-admin/syndicate-app — нет (page-isolated cream override).
7 · Hover state с color: var(--bg-secondary)¶
❌ В light это cream-on-color = слабый контраст. Cream button text на цветном bg сливается.
✅ Solid brand bg + WHITE inverse text (#FFFFFF).
8 · Closing */ посреди multi-line CSS-комментария¶
❌ Anti-pattern v4.2.8 правило 11. Если внутри комментария есть */ (например в URL /* see http://example.com/*/) — комментарий закрывается раньше времени, далее CSS rules не работают.
✅ Закрывать */ ОДИН раз в самом конце. Внутри — escapnyt * / без слэша или переписать.
9 · Premium PDF artifact как «immutable dark» в light theme¶
❌ Cert / OG / PDF deliverable не должен быть dark в light theme. Premium = light surface + gold preserved.
✅ Light cream/white surface + dark text + gold details preserved (cube/foil/corners).
CEO 5x жаловался про сертификат до v4.4.17 fix. См. feedback_certificate_canonical.md обновлённый раздел Light theme.
10 · White-on-white в hover state на chip/badge¶
❌ Race condition: idle rule с !important color + hover rule только с color: white → bg остался white из idle → invisible.
✅ Hover ВСЕГДА должен включать оба bg + color:
[data-theme="light"] .chip:hover {
background: var(--brand-color, #998018) !important;
color: #FFFFFF !important;
box-shadow: 0 4px 18px var(--brand-color) !important;
}
См. courses.html L1 chip fix v4.4.17 как канонический пример.
Audit checklist для light theme (Призма 2)¶
Per экран:
- [ ] Toggle ☀ light theme
- [ ] Header текст WHITE (не чёрный, не невидимый)
- [ ] Body bg cream #FAFAF7 (через DevTools Computed)
- [ ] Cards white #FFFFFF с тенями (layered depth)
- [ ] Text dark #0A0A0A (не pure black)
- [ ] CTAs deep bronze #998018
- [ ] Footer соответствует контексту (UI-app cream / marketing dark)
- [ ] Btn hover: solid brand bg + WHITE text (не cream-on-cream)
- [ ] Theme switch одним кликом без перезагрузки
- [ ] Нет hardcoded rgba(255,255,255,X) в class definitions
- [ ] Hover states имеют bg + color оба
- [ ] Premium artifacts — light surface + gold preserved
- [ ] Locked-chip / badge bg + color оба меняются на hover
- [ ] Computed verify через getComputedStyle()
- [ ] Zoom screenshot ДО показа CEO
См. полный аудит-протокол в 09-audit-checklist.md Призма 2.
Migration: dark→light для нового элемента¶
Шаги для каждого нового CSS class:
- Default values — пиши для dark theme (это default через root tokens)
- Token usage — все цвета через
var(--token), не hardcoded - Light test — открой в Chrome MCP, переключи light, computed style проверь
- Override if needed — если visual broken, добавь
[data-theme="light"]rule - Verify обе темы — switch RU↔EN если есть i18n
- Documentation — отметь в commit
+ light theme handled
Когда читать¶
- Перед любой работой со светлой темой — обязательно
- При computed-style debugging (почему элемент невидим) — да
- При создании override в master CSS — обязательно (не дублировать existing)
- При аудите Призмы 2 — обязательно
- При onboarding — после
01-mental-models.mdи02-tokens-canonical.md - При жалобе CEO «не работает в светлой теме» — first source of truth