capsrock/nordic-civic-design-skill

Nordic Civic Design

Based on HDS values, this is a guideline for creating public service screens. It is an unofficial skill not affiliated with the City of Helsinki.

It is not intended to make screens look like official city services. The skill uses numerical values and compositional ideas, not city-identifying elements.

What Not to Use

• Logo, coat of arms, wave motif: The logo is a registered trademark; reproduction or modification is not permitted. The wave motif is a visual element of the city, and third-party usage rights have not been verified.
• Helsinki Grotesk font files: A commercial typeface from Camelot Typefaces, redistribution and AI training use are prohibited. Do not bundle or embed it on the web or in apps. Only specify the font name in CSS.
• Expressions claiming to be "City of Helsinki": Do not include words that could be mistaken as official city branding in the name or body of the deliverable.

Typography

font-family: HelsinkiGroteskPro, "Schibsted Grotesk", Arial, "Noto Sans JP", sans-serif;

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700&family=Schibsted+Grotesk:wght@400;500;700&display=swap">

In environments where the user has a license, the original typeface will be used; otherwise, Schibsted Grotesk falls back. This is a choice of this skill, not an HDS specification. The official HDS fallback is Arial.

Schibsted Grotesk is available under OFL 1.1 with weights from 400 to 900. The three HDS weight levels (400, 500, 700) are used directly.

HDS does not specify Japanese text. For Japanese screens, Noto Sans JP is the default with a line height of 1.75. This is also a decision of this skill.

Shapes

The shape guidelines are central to the HDS-like appearance. Breaking them significantly changes the overall impression.

• Border radius is 0: Used for all buttons, input fields, and cards.
• Border width is 2px: Used for buttons, input fields, and card borders.
• Interactive elements are 56px tall: Standard for buttons and input fields. Small buttons are 44px tall.
• No shadows: HDS explicitly states that shadows are not part of the brand. Do not use shadows for layering, emphasis, or text decoration. Use shadows only for toast notifications and dialogs that overlay content.
• Cards are borderless by default: The HDS default. Borderless cards are placed on a light gray (--color-black-5) surface. When placed on a white background, use a 2px border. The handling of white backgrounds is a decision of this skill.
• Notifications have an 8px left band: Do not fill the entire area with strong color; use a light background and a left band to convey the message.

Colors

Values are in references/tokens.css, and a table of usage and contrast ratios for each color is in references/foundation.md. Color names (bus, tram, metro, engel, etc.) are inspired by the Helsinki cityscape.

• Primary action color is bus: Use --color-bus (#0000bf) for primary actions and links. Hover is --color-bus-dark.
• Focus outline is coat-of-arms: Use a 3px outline of --color-focus-outline. On dark backgrounds, use white.
• Body text is black-90: --color-black-90 (#1a1a1a). Body text color is either black or white; use other colors only with intention.
• Accent colors are used for large surface areas: Colors like summer, suomenlinna, and metro are used for heading bands or dividers. Scattering them in small amounts reduces impact. Aim for one color per screen. This is a decision of this skill.
• Only 4 brand colors can be placed as text on white: bus, brick, coat-of-arms, and tram. metro is for large text only; bright colors like summer and engel are used only as background surfaces on white.
• Do not use -light and -dark variants as primary colors: Use them only for component states (e.g., hover) or to differentiate types of information.
• Separate state colors from accent colors: Use error, success, alert, and info only to convey status. Do not use brand colors for status indicators. Always accompany color with text or an icon.

All text/background combinations must meet WCAG 2.1 AA contrast ratios: body text 4.5:1+, large text 3:1+. Text on brand colors follows the table in foundation.md (white on bus, coat-of-arms, tram, brick; black-90 on others). Gray text is limited to --color-black-60; do not use --color-black-50 or lighter on white backgrounds.

Spacing

The base unit is 4px. Use --spacing-* and --spacing-layout-* tokens; do not create intermediate values.

• Internal component spacing and spacing between components: 8, 12, 16, 24, 32px from --spacing-*.
• Section spacing: 48, 64, 96, 128px from --spacing-layout-*.
• Group with small spacing, separate with large spacing: Closely related items appear related. Items with larger spacing appear more important.
• Adjust density based on screen purpose: Screens for public information or guidance use wider spacing; information-dense administrative screens use tighter spacing.

When in doubt, choose wider spacing. Generous whitespace creates a calm screen. This sentence is a decision of this skill. Use a 12-column grid with a maximum width of 1200px and a gutter of 24px (16px on mobile).

Typography

• Three weight levels: Body text 400, button and form labels 500, emphasis 700.
• Body text starts at 16px: 16px is the HDS minimum for body text and works at all screen widths. For screens with little text, default to 18px, reducing to 16px on narrow screens. 14px is reserved for supplementary text and within components.
• Headings have two scales: Desktop: h1 at 64px, h2 at 48px. Mobile and administrative screens: h1 at 40px, h2 at 32px. Use heading hierarchy semantically; if you only need to change appearance, use tokens to adjust size.
• Line height: Long body text 1.5, short paragraphs and lead text 1.2, single-line headings and components 1, small text and quotes 1.75.

Default heading weight is 700. This is a decision of this skill; HDS documentation does not specify heading weights. A table of values and usage is in references/foundation.md.

Components

Read references/components.md before building components. It contains values and usage for buttons, input fields, checkboxes, notifications, cards, and links. Key points:

• One primary button per screen: Only for the most important action. Cancel or close buttons use the supplementary style; since they have no border, include an icon. Page navigation uses links, not buttons.
• Always label input fields: Mark required fields with * and explain the meaning of the mark at the top of the form.
• Use notifications only for important information: Aim for no more than one inline notification at a time; do not add dynamically. Important notifications (e.g., errors) should not auto-dismiss.
• Do not make an entire card clickable: If you need the whole area to be clickable, use a Linkbox.
• External links get an icon: As a rule, do not open them in a new tab.

For components not listed here, assemble them based on the guidelines for shapes, colors, and spacing. Do not write values as HDS values if they have not been verified against HDS.

Validation Checklist

After finishing, check the following:

1. No border radius or shadows remain (except for toast notifications and dialogs)
2. No non-token color or spacing values are used
3. Interactive elements have a height of at least 44px
4. Focus outlines are visible
5. Text/background contrast ratios meet WCAG 2.1 AA
6. No logo, wave motif, or city name is used

Sources

Token and component values are taken from hds-design-tokens and hds-core 6.0.7; usage information is from official HDS documentation (https://hds.hel.fi/, original files in the same repository under site/src/docs). All are under MIT License, Copyright (c) 2023 City of Helsinki. The license text is in references/LICENSE-HDS.txt. When distributing this skill, include that file. Color name origins follow the City of Helsinki visual identity guidelines.