CSS Styling & Theming
Relevant source files
The following files were used as context for generating this wiki page:
The CSS Styling and Theming system in the CircleCI Docs project is a multi-layered architecture designed to separate documentation content from its visual presentation. It integrates a custom UI theme with Tailwind CSS, standard CSS stylesheets, and Antora-driven attributes to provide a responsive and branded documentation experience.
The primary purpose of this system is to maintain visual consistency across various documentation components—ranging from core guides to technical references and server administration pages—while allowing for specific customizations such as status badges and admonition styles. Sources: ARCHITECTURE.md:16-20, README.md:12-16
Architectural Overview
The styling architecture follows a modular approach where the UI is bundled separately from the content. The system relies on a combination of utility-first CSS and component-specific stylesheets.
Core Components of the Styling System
| Layer | Implementation | Description |
|---|---|---|
| Framework | Tailwind CSS | Provides utility classes for layouts, spacing, and responsive design. |
| Theming | CSS Variables | Defines colors, font sizes, and margins (e.g., --doc-font-size). |
| Components | doc.css | Handles complex documentation elements like tables, admonitions, and code blocks. |
| Bundling | Gulp / UI Bundle | Compiles source files into a ui-bundle.zip consumed by Antora. |
Sources: TECHNICAL_REFERENCE.md:120-135, DEVELOPMENT.md:118-135
Style Processing Flow
The following diagram illustrates how CSS sources are processed and applied to the final static site output.
The build pipeline combines source CSS with framework utilities to generate the final optimized site assets.
Sources: ARCHITECTURE.md:65-80, TECHNICAL_REFERENCE.md:78-85
Component-Specific Styling
Documentation Body (.doc)
The main content area is managed via the .doc class, which controls core typography and responsive spacing. It uses CSS variables to ensure consistency across desktop and mobile views.
- Desktop View: Flexbox is utilized with an "aggressive fix" for screens wider than 1200px to force content centering and ignore excessive content width.
- Typography: Headings (h1-h6) use specific font weights and line heights (1.3), with anchor links becoming visible upon hover.
Sources: ui/src/css/doc.css:1-50, ui/src/css/doc.css:105-120
Admonitions and Sidebars
Admonitions (NOTE, TIP, IMPORTANT, etc.) are styled with specific border colors and icons to provide visual cues to the user.
| Type | Border Color | Icon Asset |
|---|---|---|
| Note | #1A66F7 | note_icon.svg |
| Tip | #697387 | tip_icon.svg |
| Warning | #BF8532 | alert_icon.svg |
| Important | #CC4242 | caution_icon.svg |
Sources: ui/src/css/doc.css:342-385
Code Blocks and Syntax Highlighting
Code blocks use a dark theme background (--pre-background) and are styled to preserve whitespace while allowing for custom toolbox interactions like "copy to clipboard."
- Toolbox: Appears on hover, containing a copy button and language identifier.
- Formatting: Uses the
highlight.js(hljs) standard for line numbering and code wrapping within tables.
Sources: ui/src/css/doc.css:570-620, TECHNICAL_REFERENCE.md:138-145
Content-Driven Styling (Badges)
Authors can influence the UI directly from AsciiDoc files using page attributes. A notable feature is the Page Title Badge system, which allows visual status indicators (Preview, New, Deprecated) next to page titles.
= Page Title
:page-badge: Preview
:page-badge-classes: text-white bg-orange-500 border border-orange-600
Sources: CONTENT_AUTHORING.md:60-90
Diagramming System (Mermaid)
The project integrates antora-mermaid-extension to render diagrams from text. Styling for these diagrams is configured globally in the playbook.
Mermaid diagrams are themed via theme_variables in the project configuration to match the overall site aesthetics.
Sources: antora-playbook.yml:68-78
Conclusion
The styling and theming system of the CircleCI Docs project represents a robust integration of modern web tools. By combining Tailwind CSS for rapid layout development with localized CSS components for documentation-specific needs, the project achieves a high degree of maintainability. The ability for content authors to inject styles through AsciiDoc attributes further enhances the flexibility of the platform. Sources: ARCHITECTURE.md:84-90, DEVELOPMENT.md:140-150