Prohlížeč zdrojového kódu

docs/specs/styling.md

Náhled Zdrojový kód 

# Spec: Styling and CSS



- **Status:** active

- **Created:** 2026-03-05

- **Related code:** `app/assets/stylesheets/`, `app/javascript/controllers/theme_controller.js`, `app/views/layouts/application.html.erb`



## Overview



The app uses Pico CSS v2 as a base design system, extended with custom SCSS partials compiled by Dart Sass via Sprockets. The styling system provides a consistent visual theme across all pages, supports both light and dark modes, and handles syntax highlighting for code display.



## Behaviour



### Stylesheet compilation

- `application.scss` is the entry point; it loads `pico.min.css` via a Sprockets `require` directive, then `@use`s all SCSS partials.

- Partials are: `variables`, `layout`, `cards`, `code`, `results`, `home`, `rouge`, `source`.

- Compilation is handled by `dartsass-sprockets` (no separate Sass watcher process needed).



### Typography

- Inter (from Bunny Fonts CDN) is the sans-serif font; a monospace stack (SF Mono → Cascadia Code → Fira Code → Consolas) is used for code.

- Fonts are loaded via `<link>` in the layout head.



### Dark mode

- `data-theme="light|dark"` on `<html>` drives all theme CSS. See [themes.md](themes.md) for full behaviour.



### Custom tokens

- `_variables.scss` overrides Pico CSS custom properties at matching specificity to avoid `!important`.

- Custom tokens for result boxes (`--color-result-ok-*`, `--color-result-err-*`) are defined for both light and dark in `_variables.scss`.



### Syntax highlighting (Rouge)

- `rouge.scss` provides GitHub Light colour rules for `.highlight` (default) and GitHub Dark rules under `[data-theme="dark"] .highlight`.



### Page-specific partials

- `_layout.scss` — sticky footer (flex body), flash message styles

- `_cards.scss` — `.tag`, `.tag-filter`, `.tag-filters`, `.examples-grid` (auto-fill grid)

- `_code.scss` — `.code-block` with scrollable `<pre>`

- `_results.scss` — `.result-box` (success/error variants), `.result-meta`

- `_home.scss` — `.hero` centred section

- `_source.scss` — two-column source browser layout, sticky tree sidebar, `.tree-file` active state, responsive collapse at <=768px



### Conventions

- Custom styles prefer Pico CSS variables (`--pico-*`) over hardcoded values where an equivalent exists.

- No utility-class frameworks (no Tailwind/Bootstrap).

- The scenario form uses bare `<label>` + `<select>` pairs without wrapper divs.



## Implementation Notes



- `pico.min.css` is vendored in `app/assets/stylesheets/` and loaded via Sprockets `require` (not `@use`) because it is plain CSS, not SCSS.

- Dart Sass is provided by `dartsass-sprockets` gem; no separate watcher process is needed in development.

- `_variables.scss` uses `:root:not([data-theme="dark"]), [data-theme="light"]` to match Pico's own specificity (0,2,0) so overrides win by source order without `!important`.

- Theme switching implementation details are in [themes.md](themes.md).



## Tests



No automated tests — visual styling is verified manually.



## See Also



- [Home Page](home-page.md) — `_home.scss` styles the hero section; `_cards.scss` styles the examples preview grid.

- [Source Browser](source-browser.md) — `_source.scss` provides all Source Browser layout and tree styles.

- [Examples Runner](examples-runner.md) — `.result-box` and `.code-block` are the primary styled outputs of the runner.

- [Light/Dark Theme Switching](themes.md) — detailed spec for the theme toggle behaviour and persistence.

- [Markdown Code Block Syntax Highlighting](markdown-code-highlighting.md) — uses `rouge.scss` colour rules for code blocks inside rendered Markdown.



## Change Log



- 2026-03-05: Retrospective spec written documenting current state.