entur-web-development

name

entur-web-development

description

Build React applications with Entur Linje @entur/* component packages. Use when the user is installing, importing, or using any @entur/* package, asking about Entur React components, Entur tokens, Entur CSS variables, Entur design system in a development context, or building web UI that should follow Entur's component library. Trigger for any code task involving @entur/button, @entur/form, @entur/tokens, @entur/typography, @entur/travel, or any other @entur/* package — even if the user just describes wanting to build something that fits Entur's look and feel in React.

Audience: AI coding agents. Entur developers should visit linje.entur.no/komponenter.

Entur Web Development

This skill helps you build correct, accessible, on-brand React applications using Entur Linje's @entur/* component packages.

The component library solves three things at once: components look right (Entur brand), behave right (keyboard, screen reader, focus management), and feel right for users of Entur products. Use the components rather than reimplementing them from scratch.

Full component docs: https://linje.entur.no/komponenter
GitHub: https://github.com/entur/design-system

---

Critical Rules

1. ALWAYS check references/components.md before building custom UI. The design system covers buttons (7 variants), forms, navigation, modals, tables, accordions, tabs, alerts, chips, dropdowns, loaders, travel components, and layout primitives.
2. ALWAYS import @entur/tokens/dist/base.css first, before any component stylesheets. Then import component CSS in the exact order in references/getting-started.md. Wrong order causes visual regressions.
3. ALWAYS use tokens from @entur/tokens for color, spacing, and typography. Never hardcode hex or rgb values — they break dark mode and drift from the brand.
4. NEVER override @entur/* component styles by targeting .eds-* internal selectors, using !important, wrapping in CSS-in-JS, or applying inline style props. DS components have calibrated styles for contrast, dark mode, and interaction states. Adding a className as a scoped override anchor is only permitted via the exception below.
5. NEVER apply padding or margin directly to @entur/* components — wrap them in a layout element instead.
6. ALWAYS add SkipToContent from @entur/a11y as the first element in every app, with a matching <main id="main-content">.
7. ALWAYS use visible label props on form fields — never rely on placeholder alone.
8. NEVER use default imports from @entur/* packages — all exports are named.

Exception for rules 4 & 5: When the user explicitly asks for a visual deviation, you may override component styles. Follow this approach:

1. Add a className to the component — this is your selector anchor. Never target .eds-* internal class names directly.
2. Use the following token priority for color values:
   • Component tokens first — --components-{package}-{variant}-{context}-{property} CSS custom properties (e.g. --components-button-primary-standard-fill). These live in each package's compiled styles.css and are scoped to the component's own context. Not officially documented for consumers but preferred when deviating.
   • Base tokens second — --basecolors-* from @entur/tokens/dist/base.css
   • Semantic tokens third — --fill-*, --text-*, --stroke-* from @entur/tokens/dist/semantic.css
3. Never use !important — if specificity is a problem, increase it via the className selector chain.
4. Add a short comment on the CSS rule marking the intentional deviation so it can be tracked and revisited.

// Component gets a className as the override anchor
<PrimaryButton className="booking-hero-cta">Kjøp billett</PrimaryButton>

/* intentional deviation — booking hero requires coral background */
.booking-hero-cta {
  --components-button-primary-standard-fill: var(--shape-highlight);
}

Rules 3 (no hardcoded hex), 6 (SkipToContent), 7 (form labels), and 8 (named imports) still apply regardless of deviation.

Warning: Overriding component styles breaks visual consistency, may break dark mode, and creates a maintenance burden when the design system evolves. Before proceeding, inform the user of these risks and suggest they consult the design system team in #talk-designsystem on Slack — there may be an existing component variant, a planned addition, or a better approach.

---

Golden Path

Adding a component to an Entur app:

# 1. Install
yarn add @entur/button @entur/tokens

/* 2. Import CSS globally (App.tsx or global stylesheet) — tokens first */
@import '@entur/tokens/dist/base.css';
@import '@entur/button/dist/styles.css';

/* 3. Import component (named export) */
import { PrimaryButton } from '@entur/button';

/* 4. Use — accessible, branded, dark-mode-ready out of the box */
<PrimaryButton onClick={handleSubmit}>Kjøp billett</PrimaryButton>;

---

Reference files

Read these when you need specifics:

• references/getting-started.md — installation, full CSS import order, SCSS @use pattern, TypeScript types, dark mode setup, troubleshooting
• references/components.md — full component catalog with usage examples (buttons, forms, navigation, layout, travel, etc.)
• references/tokens-and-variables.md — complete CSS custom property reference for semantic, base, transport, and data tokens; JS import patterns

---

Quick reference

Install: yarn add @entur/button @entur/tokens
CSS import order: See references/getting-started.md
All imports are named: import { PrimaryButton } from '@entur/button'
Light/dark mode: data-color-mode="dark" on a parent element
Deduplicate packages: yarn dedupe --pattern "@entur"
Questions?: Slack #talk-designsystem

Beyond Entur

For general React/web best practices beyond Entur's design system, these community skills exist:

• vercel-labs/agent-skills@vercel-react-best-practices — React/Next.js patterns
• addyosmani/web-quality-skills@performance — web performance
• addyosmani/web-quality-skills@core-web-vitals — Core Web Vitals