Custom components

Build your own components using EthioWDS class names and design tokens so they look and behave consistently with the rest of the design system.

What are custom components?

Custom components are pieces of UI you build for your project—cards, panels, forms, or patterns—that are not part of the core EthioWDS set. By using the same class names, spacing, and colors as the design system, your custom components fit visually and stay maintainable.

How to build custom components

1. Use design system class names

Reuse existing component classes where they fit. For example, use eth-button and eth-button--primary for buttons inside your component so they match the rest of the site. Browse Components for available classes.

2. Use design tokens for spacing and color

Use the same spacing scale and colors the design system uses. That usually means using the same custom properties (e.g. var(--primary), var(--ethio-gray-100)) or utility classes for margins, padding, and backgrounds. See CSS variables and Spacing.

3. Keep structure and naming consistent

Name your own classes in a clear, consistent way (e.g. a prefix for your project or section). Reuse the same patterns for focus states, hover states, and responsive behavior so custom components feel like part of the system.

Example: custom card

A simple custom card that uses design system tokens and a button:

<div class="my-card" style="padding: 1rem; border: 1px solid var(--ethio-gray-200); border-radius: 0.5rem; background: white;">
  <h3 style="margin: 0 0 0.5rem 0; color: var(--ethio-gray-900);">Card title</h3>
  <p style="margin: 0 0 1rem 0; color: var(--ethio-gray-700);">Card content goes here.</p>
  <button class="eth-button eth-button--primary">Action</button>
</div>

Here, spacing and colors use the same variables as the design system; the button uses the standard EthioWDS button classes.

Step-by-step: create a custom component

  1. Make sure EthioWDS is installed and its stylesheet is loaded (see Installation).
  2. Choose the right building blocks: use existing components (e.g. buttons, inputs) and design tokens (colors, spacing) from CSS variables and Design tokens.
  3. Build your markup and apply design system classes where they fit; use variables like var(--primary) or var(--ethio-gray-200) for any custom styling.
  4. Test focus, hover, and keyboard behavior so the component is accessible and consistent with the rest of the site.

See also

Components — All EthioWDS components and class names. Theming — Theming overview. Guidance — Design principles and best practices.