Customise CSS

Overview

This page explains the process for customising, building, and publishing CSS for DIGIT UI. It covers when and how to update CSS, recommended approaches for look & feel changes, publishing to npm, and relevant code references.

If any changes are made to the CSS (either full CSS or Tailwind-based tokens), the CSS must be rebuilt and published to npm so that digit-ui can consume the updated styles.

---

Existing CSS Package

The base CSS is currently published to npm as:

• @egovernments/digit-ui-css

• @egovernments/digit-ui-components-css

This package is consumed directly by DIGIT Micro UI applications.

---

Publish Custom CSS Packages

If CSS changes are required, they can be published:

• Under the same package (not recommended unless centrally coordinated), or

• Under a different organisation or scope (recommended for state / org-specific customisations)

Example - @xyz/[email protected]

---

Update index.html

Once the CSS package is published, update the stylesheet reference in the following file:

File location: frontend/micro-ui/web/public/index.html

Example

<linkrel="stylesheet"href="https://unpkg.com/@xyz/[email protected]/dist/index.css"/>

This ensures that the Micro UI loads the correct CSS version.

---

Publish CSS

You can publish the CSS using either of the following approaches:

Option 1: From micro-ui-internals

cd frontend/micro-ui/web/micro-ui-internals 
yarn run publish:css

Option 2: From CSS package folder

cd frontend/micro-ui/web/micro-ui-internals/packages/css 
yarn run publish --access public

---

CSS Customisation Approaches

There are two supported ways to customise CSS in DIGIT UI:

---

1. Override Specific Styles (Recommended)

• Do not modify the base CSS directly

• Add only required overrides in a custom CSS package

• Include both base CSS and custom CSS in index.html

• The order of inclusion matters

  • The CSS file included last takes precedence

This approach:

• Minimises upgrade effort

• Keeps changes isolated

• Is safer for long-term maintenance

---

2. Overwrite the Entire CSS

• Replace the existing CSS completely

• Use this only if the UI requires a full redesign

⚠️ Note: If the entire CSS is overwritten, future DIGIT upgrades will require manual comparison and merging of changes from newer versions.

---

Update Colours / Look & Feel (Preferred for Theming)

If the requirement is only to update colours or basic look & feel, follow this approach instead of changing the full CSS:

1. Identify the corresponding version of the CSS from the repository that matches your DIGIT UI version.

2. Update only the Tailwind constants (colours, spacing, etc.) in the following file:

   react/css/tailwind.config.js

3. Override only the required colour tokens.

4. Rebuild the CSS.

5. Publish the rebuilt CSS to npm.

https://raw.githubusercontent.com/egovernments/DIGIT-Frontend/refs/tags/quick-start-v1.0.3/micro-ui/web/micro-ui-internals/packages/css/tailwind.config.jsraw.githubusercontent.com

This approach:

• Preserves core styling logic

• Reduces risk during upgrades

• Ensures consistent component behaviour

---

Code References

CSS Package – Framework (Micro UI)

• Repository

• Responsible for building and publishing digit-ui-css

---

CSS Package – UI Components

• Repository

• Contains:

  • Tailwind configuration

  • Design tokens

  • Component-level styling utilities

---

Reference: Publish npm Packages

For more details on publishing scoped public npm packages, refer to:

Creating and publishing scoped public packages | npm Docs

---

Create CSS for a New Module Using an Existing Theme

When the requirement is to use the same framework theme and colours and introduce a new module, there is no need to redefine or duplicate component-level styles.

In this case:

• Create a new CSS package specific to your module

• Reuse the existing DIGIT framework theme and colour tokens

• Add only module-level or page/component-specific CSS

This keeps the CSS minimal, avoids duplication, and ensures consistency with the core DIGIT UI.

Key Points

• Do not re-add existing component styles

• Focus only on module-specific layouts and overrides

• Consume the base framework CSS as-is

---

Framework & Component Base References

Use the following references as the base when creating module-specific CSS packages:

Framework Base CSS (Recommended)

• DIGIT UI framework base: https://github.com/egovernments/DIGIT-Frontend/tree/digit-ui-v1.0/micro-ui/web/micro-ui-internals/packages/css

• Quick-start reference: https://github.com/egovernments/DIGIT-Frontend/tree/quick-start-v1.0.3/micro-ui/web/micro-ui-internals/packages/css

---

UI Component CSS

• UI component styles and Tailwind configuration: https://github.com/egovernments/DIGIT-UI-LIBRARIES/tree/digit-ui-components-v0.2.1/react/css

---

Recommendation Summary

• Reuse framework CSS for theme and colours

• Create lightweight, module-specific CSS packages

• Override only what is required at the module/page level

• Avoid duplicating component CSS

• Always align framework and component versions