DOCSEARCHbyAlgolia
Submit Docs

GOV.UK Frontend

repository·main·Indexed 23 days ago

https://github.com/alphagov/govuk-frontend

Provides the essential code and components required to build user interfaces for government platforms and services, adhering to the GOV.UK Design System. It includes a library of components such as Accordion, Back link, Breadcrumbs, Button, Character Count, Checkboxes, Date input, Details, Error message, and error-summary.

Tokens
32.4K
Snippets
43
Records
261
Agent score
80%

What's inside govuk-frontend

  3. Use Override classes for high-specificity styling

    main

    The Overrides layer is used to force specific properties and override all other layers. Rules in this layer generally use !important.

    Naming Convention

    • Class names use the prefix -!-. Example: .govuk-!-font-width-regular.
    • Conditional overrides append the condition to the end of the class name. Example: .govuk-!-display-none-print will only apply display: none in a print layout.

  4. Understand browser and assistive technology support

    main

    GOV.UK Frontend categorizes browser support into four grades. Note that JavaScript enhancements will only run in grades A, B, and C. Browsers in grade X (including IE11 and older) will not receive JavaScript enhancements.

    Browser Grades

    • grade A: Most recent stable versions of Chrome, Firefox, Edge, Samsung Internet, and Safari.
    • grade B: All stable versions of Chrome, Firefox, and Edge released in the last 6 months, and the last 4 major stable releases of Safari not covered in Grade A.
    • grade C: All browsers that support <script type="module"> (e.g., Chrome 61+, Edge 16-18, Edge 79+, Firefox 60+, Safari 11+).
    • grade X: All other browsers (including IE11 and older).

    Assistive Technology

    • The library supports recommended assistive technologies.
    • The library supports users overriding colours in Windows, Firefox, and Chrome.

  5. How the Details component handles browser compatibility and styling

    main

    The details component uses a progressive enhancement strategy to handle varying levels of browser support for the <details> element, CSS feature queries, and ES6 modules:

    • Modern Browsers (supporting type=module, <details>, and feature queries): Receive full GOV.UK styling.
    • Edge 16-18 (supporting type=module and feature queries but not <details>): These are filtered out using the -ms-ime-align: auto check to ensure they don't receive interactable styles if they cannot support the component.
    • Legacy Browsers (IE 8-11): These browsers do not support <details>, type=module, or feature queries. They are styled to look like inset text using a @media screen\0 hack to prevent them from appearing interactable.
    • Opera Mini: This is a known gap where browsers support feature queries but not <details> or type=module. These browsers may appear interactable even if they are not.
    • Browsers with <details> but no module/feature query support: These fall back to native <details> styling combined with GOV.UK spacing and font styles.

    Note on JavaScript: In older browsers that require a polyfill for the <details> element, the custom marker may still be displayed even if JavaScript is disabled. This is a cosmetic issue and does not impact content accessibility.

  7. Understand the GOV.UK Frontend CSS architecture

    main

    GOV.UK Frontend follows a layered architecture inspired by ITCSS to provide a logical structure for styles. The layers are organized as follows:

    1. Settings: Global variables (colors, spacing, typography). Does not output CSS.
    2. Tools: Logic-based mixins or functions for calculations or conditional CSS. Does not output CSS.
    3. Helpers: Mixins that abstract common styling (e.g., focus states, visually hidden content). Does not output CSS.
    4. Core: Basic content styles for HTML elements like typography, links, paragraphs, and headings.
    5. Objects: Layout systems or wrapper elements that can be used in various contexts.
    6. Components: Discrete UI pieces that map to the GOV.UK Design System components.
    7. Utilities: Single-purpose utility classes (e.g., clearing floats).
    8. Overrides: High-specificity classes used to override other layers, typically using !important.

  8. Configure visual regression testing with Percy

    main

    Visual regression testing is handled via Percy. To include a component example in Percy screenshots, add the screenshot attribute to the example in the component's YAML fixture.

    Supported screenshot values:

    • true: Takes a screenshot of the example.
    • variants: ['default', 'no-js']: Takes multiple screenshots. no-js captures the component with JavaScript disabled to ensure visual consistency.

    Note: Percy commands are ignored during local testing (e.g., npm run test:screenshots). You will see the message [percy] Percy is not running, disabling snapshots in the console.

  11. How marker styling is implemented in the Details component

    main

    To ensure consistent alignment and control over the summary arrow across all browsers, the details component hides the browser's native marker and injects a custom one.

    This approach was chosen over targeting Firefox specifically with @-moz-document (which was deprecated in Firefox) or using Unicode glyphs (which caused emoji substitution issues on Android). Instead, the component uses border-based triangles to ensure consistent rendering.