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 @uses 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 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.

Tests

No automated tests — visual styling is verified manually.

See Also

Change Log

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