# dns agent design guide

You are designing, building or writing for **dns** (digital nervous systems
GmbH, Nürnberg, since 1999): a software house that builds long-lived custom
software for the German Mittelstand. This guide makes anything you produce —
a website, an app screen, a slide deck, a social post, a document, an image —
look and read as dns.

It works in any tool and any stack. Values are given as hex for design tools
and as CSS for code.

- **Part A — Visual design** applies to everything.
- **Part B — Implementation** adds what matters when you write code.
- **Part C — Wording** applies to every word a reader sees, German or English.

Treat every rule marked **must** as binding. If a request conflicts with one,
say so and propose a compliant alternative instead of quietly picking a side.
If the project you are working in has its own design documentation, it wins for
that project; this guide fills whatever it leaves open.

---

## Part A — Visual design

### 1. Character

Premium, flat, editorial B2B. Square surfaces, hairline borders, generous
space, one warm accent. It should feel **stable and unhurried**, like a
supplier you would trust with a ten-year system — never loud, playful or
"startup".

Three things carry the brand: the **warm off-white base**, the **amber
accent**, and the **square, flat surface**. Everything else is typography and
space. When in doubt, remove rather than add.

### 2. Colour

| Name | Hex | Token | Use |
| --- | --- | --- | --- |
| **Amber** | `#F59C00` | `primary` | The only accent: buttons, icons, numbers, rules, glows, highlights |
| **Ink** | `#0B0B0C` | `ink`, `primary-content` | Dark sections and panels; text on amber |
| Paper | `#FCF8F3` | `base-100` | Cards, tiles, hero background |
| Sand | `#F1EAE3` | `base-200` | Page / section background |
| Line | `#E2D9D0` | `base-300` | Structural dividers |
| Text | `#09090B` | `base-content` | Text on light surfaces |
| **Highlight** | `#FBE6C2` | amber at 20 % | The emphasis mark behind a word (§4) |

- **One amber, no variants.** No lighter or darker amber, no second accent, no
  gradients between colours, no other hues (no blue links, green ticks, red
  accents).
- **Do not darken amber for contrast.** As text on the light surfaces it
  measures 2.06:1 and fails WCAG AA — an accepted, deliberate trade-off. A
  darker amber reads as brown and stops being the brand. Keep amber text short
  (a number, a label, a link), never sentences. On Ink amber is 9.03:1; do not
  fade it below 70 % there.

**Text colours — three roles, one floor.** Use opacity where the tool supports
it, otherwise the solid values.

| Role | On Paper | On Ink |
| --- | --- | --- |
| Primary — headings, key text | Text 100 % (18.9:1) | White 100 % (19.4:1) |
| Secondary — body, intros | Text 70 % ≈ `#525151` (7.48:1) | White 70 % ≈ `#B6B6B6` (9.70:1) |
| Tertiary — captions, meta | Text 60 % ≈ `#6A6968` (5.18:1) | White 55 % ≈ `#919192` (6.25:1) |
| **Floor — never lighter** | **60 %** | **45 % ≈ `#797979`** (4.52:1) |

Anything below the floor is for non-text only: borders, dividers, glows.

**Hairlines:** Text at 8 % on light (≈ `#E9E5E0` on Paper), white at 8 % on Ink
(≈ `#1F1F1F`).

A surface is dark whenever the pixels behind the text are dark — including a
photo under a dark gradient scrim. Use the white ramp there.

### 3. Typography

Two typefaces, both free on Google Fonts. No third face, no serif, no script.

- **Manrope** — headings.
- **Inter** — body text, interface, captions.

| Role | Size (mobile → desktop) | Weight | Line height |
| --- | --- | --- | --- |
| Page title (`h1`, one per page) | 36 → 60 px | Bold | 1.1 |
| Utility title (legal pages) | 30 → 36 px | Bold | normal |
| Section heading (`h2`) | 24 → 30 px | Bold | 1.25 |
| Statement (CTA, banner `h2`) | 30 → 48 px | Bold | 1.1 |
| Card / row title (`h3`) | 18 px | Semibold | normal |
| Intro | 18 px | Regular, secondary colour | 1.6 |
| Body | 16 px | Regular, secondary colour | 1.6 |
| Caption, card body | 14 px | Regular, tertiary colour | 1.6 |

Off the web, scale proportionally and keep the ratios.

- Headings: letter-spacing about −1 % plus tight tracking, **sentence case**.
- **Never tighter than 1.1 line height** on large type — German capital umlauts
  (Ü, Ä, Ö) collide with the line above.
- Body measure: roughly 60–75 characters per line.

### 4. No eyebrows, and how to emphasise

**No eyebrows — must.** Nothing sits between the start of a block and its
heading: no small uppercase label, badge, tag, chip, pill, logo row, stat strip
or image above a title or section heading. A section already announces itself
through its background change, its spacing and its heading. If something has
to come first visually, make it its own block beside the one with the heading.

Two sanctioned exceptions only:
1. the **step number** (`01`, `02`) above the heading of a section that is one
   step of a numbered sequence shown on the same page;
2. the **service-name pill** above the title of a service page hero.

**Emphasis — the highlight mark.** To stress one word or short phrase, put the
**Highlight** colour behind it as a soft mark (≈ 2 × 8 px padding, 4 px corner
radius — the one radius exception) and keep the text in Text colour.

- **One emphasis per headline**, at most. Two cancel out.
- **Light backgrounds only.** On Ink, headlines stay plain white. If a dark
  headline genuinely needs it, colour the word amber at 80 % (`#C67F02`) with
  no fill — never a block.
- **Never colour words amber** on light to emphasise them; it reads as a link
  and is the least legible thing on the page.

> Example: *KI, die* **[messbar]** *Arbeit abnimmt.* — the mark sits behind „messbar“.

### 5. Layout and space

- **Width:** content capped at 1280 px, centred, 24 px side margins. On slides
  and documents, keep consistent margins of the same proportion.
- **Section spacing — two values only:** standard 80 → 112 px; emphasis
  96 → 128 px (hero, CTA, the section right after the hero).
- **Gaps:** 24 px within a grid; 48 → 64 px between large blocks; on dark,
  cells may be separated by 1 px hairlines instead of gaps.
- **Background sequence:** alternate Sand → Paper → Ink so neighbouring sections
  stay distinct. Dark sections are emphasis — keep them rare. Two dark ones in
  a row need a clear break (a hairline, a bordered grid, or their own heading
  and full spacing).
- **Dark panel on light:** to make one block stand out, inset a square Ink
  panel into a Sand section rather than turning the section dark. Padding
  40 / 64 / 80 px, an amber light field as texture (not a photo), plain white
  headline, no label above it, one filled button plus one text link.

### 6. Surfaces and shapes

- **Square:** cards, images, panels, sections — radius 0.
- **Round only for** buttons, pills, dots, avatars (fully round). Input fields:
  8 px. Nothing in between.
- **Flat:** a card is Paper on Sand (or the reverse) with a 1 px hairline, no
  shadow. Padding steps 24 / 32 / 32 → 48 px. On Ink, the hairline is white 8 %.
- **Shadows only on what floats** above the page: menus and dropdowns (large
  soft shadow), drawers and dialogs over a dimmed page (stronger shadow).
- **Clickable card hover:** the border turns amber at about 40 %. No lift, no
  scale, no shadow.

### 7. Heroes and title slides

- **Must:** always light (Paper). Never a dark hero or a dark title slide.
  A photographic hero fades down to Paper.
- Order: title → one-sentence subline → optional button pair. Nothing above the
  title (except the service pill, §4).
- Texture, from most to least:
  - **Wash:** three large, heavily blurred amber blobs (≈ 700 px, 15–20 %
    opacity, blur 100–140 px) — for light heroes without a photo.
  - **Rule:** a 3 px amber edge along the top plus one faint low-left blob
    (≈ 9 %, blur 170 px) — for type-only heroes where a wash reads as a gradient.
  - **None:** a plain light hero is fine where the content below carries the amber.
- On Ink, glows are two faint blobs (7 % and 4 %) or one (6 %). Scale blobs down
  on small panels, or they wash the surface brown.

### 8. Buttons and links

All buttons are pills, in a "liquid glass" style: translucent fill, backdrop
blur ≈ 20 px, a thin inner highlight along the top edge.

| Variant | Look | Use |
| --- | --- | --- |
| Primary | Amber at 88 %, Ink text, soft amber glow | Main action on any background |
| Dark | Ink at 82 %, white text | Main action on light |
| Outline | White at 55 %, Ink text | Secondary on light |
| Glass | White at 10 %, white text | Secondary on dark or over imagery |
| Ghost | Transparent, text 60 % → 90 % on hover | Navigation, low-emphasis actions |

- **Never two filled buttons side by side.** One filled plus one outline/glass.
- **Links in running text:** amber, semibold, underlined; the underline drops on
  hover. External links open in a new tab.
- **Standalone links** („Mehr erfahren ›“): text plus a trailing arrow; the only
  hover effect is the arrow nudging forward.
- Amber text on light **does not change colour on hover** (lighter is only
  fainter); use the underline (offset 4 px) or the arrow. On dark, amber may
  fade to 80 % on hover.

### 9. Labels and numbers

- **Badge** — the only label device: solid amber block, Ink text, 10 px bold
  uppercase, slight tracking, 2 × 8 px padding, square. It labels an **object**
  (a card, a status) and sits above a card title — never above a section heading.
- **Service pill** — fully round, amber 40 % border, amber 10 % fill, 14 px
  semibold Text colour, 6 × 16 px padding. Only above a service-page title.
- **Step number** — `01`, `02`: 12 px bold, widest tracking, amber (70 % on Ink),
  always zero-padded.
- Large metrics may be amber on Ink; on light, set them in Text colour.

### 10. Icons

Heroicons 24 px outline (or a matching single-stroke outline set), in amber.
**Bare** — no circles, boxes or containers. 24 px for section and card icons,
20 px inline with text, 16 px for chevrons and arrows.

### 11. Logo

- Black logo on light backgrounds, white logo on dark. Use the SVG files from
  the brand kit.
- **Must not:** recolour, stretch, rotate, outline, add shadow or glow, rebuild
  it in another font, or place it on a busy part of a photo.

### 12. Imagery

- Calm, warm, architectural: natural light, soft shadows, warm neutral walls,
  real materials. The dns Teams background is the reference mood.
- Colour grading warm and close to Paper/Sand; amber at most as an accent.
- **Avoid:** generic stock of people pointing at laptops, handshakes, glowing
  circuit boards, blue "tech" imagery, glossy AI-looking renders, mascots.
- Text over a photo is white on a dark gradient scrim — never without one.
- On a dark promotional panel, the texture is the amber light field, not a photo.

### 13. Motion

- Ease-out (expo-out, `cubic-bezier(0.22, 1, 0.36, 1)`), about 0.6 s, small
  upward fade-ins, staggers of about 0.08 s capped at four steps.
- Reveal once; never re-animate on every scroll pass. No bounce, spin or loops.
- **No entry animations on mobile (below 768 px)** — content appears
  immediately. Hover, focus and user-triggered transitions stay.
- Honour reduced-motion settings. Motion never carries meaning.

### 14. Accessibility

- Respect the text floors in §2; amber-on-light is the one accepted exception.
- Never convey meaning by colour alone.
- Minimum 14 px for anything read on screen.
- Every interactive element has a visible focus state; anything shown on hover
  also shows on keyboard focus.

---

## Part B — Implementation

For agents that write code. Part A still applies in full; this adds how.

### 15. Tokens

Define once, reference everywhere. **A colour literal outside the token
definition is a bug** — no hex in components, no ad-hoc greys, no extra radii.

```css
:root {
  --color-primary: #F59C00;          /* amber */
  --color-primary-content: #0B0B0C;  /* text on amber */
  --color-ink: #0B0B0C;
  --color-base-100: #FCF8F3;         /* oklch(98% 0.007 70) */
  --color-base-200: #F1EAE3;         /* oklch(94% 0.012 70) */
  --color-base-300: #E2D9D0;         /* oklch(89% 0.016 70) */
  --color-base-content: #09090B;     /* oklch(14% 0.004 286) */

  --radius-box: 0;
  --radius-pill: 9999px;
  --radius-field: 0.5rem;

  --font-display: "Manrope", sans-serif;
  --font-body: "Inter", sans-serif;
}

h1, h2, h3, h4 { font-family: var(--font-display); letter-spacing: -0.01em; }
body { font-family: var(--font-body); background: var(--color-base-200); color: var(--color-base-content); }
```

**Tailwind v4:** declare the colours in `@theme` so `bg-primary`, `bg-ink`,
`bg-base-100`, `text-base-content/70` exist. Text roles then read
`text-base-content` / `/70` / `/60` on light and `text-white` / `/70` / `/55`
on dark; hairlines `border-base-content/8` and `border-white/8`. Spacing maps
to `py-20 md:py-28` (standard), `py-24 md:py-32` (emphasis), `gap-6`,
`gap-12 md:gap-16`, `max-w-7xl mx-auto px-6` for the container.

### 16. Highlight mark

```css
mark.highlight {
  background: color-mix(in srgb, var(--color-primary) 20%, transparent);
  color: var(--color-base-content);
  font-style: normal;
  padding: 0.125rem 0.5rem;
  border-radius: 4px;
  -webkit-box-decoration-break: clone;
  box-decoration-break: clone;   /* clean breaks across wrapped lines */
}
```

Use semantic `<mark>`. Tailwind: `bg-primary/20 text-base-content not-italic
px-2 py-0.5 rounded-[4px] [box-decoration-break:clone]`.

### 17. Focus

```css
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
  border-radius: 2px;
}
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
}
```

Never remove an outline without replacing it with something at least as
visible. Copy actions (copy colour, copy link) announce their result through an
`aria-live` region.

### 18. Components

- **One visual pattern, one component.** Use the one that exists. Extract on the
  **second** occurrence — not the third, not "once it is clearly reused" — and
  document it where the team will look. A near-copy with one class changed is a
  missing prop.
- The minimum set that keeps the rules in one place: **Tile** (flat card
  surface and padding steps), **FloatingPanel** (the only place a shadow lives),
  **Button** (all variants), **PageTitle** and **SectionHeading** (the type
  roles), **Highlight**, **Badge**, **StepNumber**, **ArrowLink** (link with
  arrow), **InlineLink** (link in prose), **GlowField** (hero and panel light),
  **AnimateIn** (the only entry-motion wrapper, enforcing §13).
- Semantic HTML: one `<h1>` per page, headings in order, buttons for actions,
  links for navigation.

### 19. Copy in code

- Keep user-facing strings out of components, in content files keyed by locale
  (`de`, `en`). Type the English against the German so a missing translation
  fails to compile.
- Change German and English in the same edit.
- German is primary: layouts must survive long compounds
  („Digitalisierungsstrategie“) without overflow or awkward breaks.

---

## Part C — Wording

### 20. Who we write for

Decision-makers in the German Mittelstand: Geschäftsführung, Bereichsleitung,
IT-Leitung. They weigh effort, risk and budget, and need wording they can
repeat to a board or a colleague without rephrasing. They are not judging our
craft.

Every piece should let the reader answer: **What do I get? What does it cost me
in effort or risk? Can I show this to someone above me?**

### 21. Two registers — keep them apart

**Headlines, titles, badges, buttons: short and confident.** Four to seven
words, one idea, full stop.

> „Klarheit vor Code.“ · „Software, die Ihr Geschäft kennt.“ · „Für Sie da. Auch nach dem Go-live.“

**Body, lists, FAQ answers: plain and factual.** Name the thing, then one
sentence on what it is good for. No build-up, no reveal. About 15–25 words per
sentence; none over 30.

> „Automatisierte Tests, Deployment-Pipeline und Monitoring sind Teil des Lieferumfangs.“

### 22. Do not oversell

dns should read like a competent supplier describing a scope of work — not like
the company that invented the industry.

- **Show the behaviour, do not claim the virtue.** „einschließlich derer, von
  denen wir abraten“ says more than „eine ehrliche Bewertung“. Avoid bare
  claims like *transparent, partnerschaftlich, pragmatisch, erfahren*.
- **Drop the contrast tic.** „nicht X, sondern Y“ / „statt Y“ at most once per
  section, and only when the contrast tells the reader something new.
  - ✗ „Wir bauen nicht neben Ihre IT, sondern hinein.“
  - ✓ „Anbindung an ERP, CRM und vorhandene Fachanwendungen.“
- **No swipes at other providers** inside our own claims. Naming the customer's
  pain is fine („Der Dienstleister hat geliefert und ist verschwunden.“).
- **No superlatives or absolutes:** einzigartig, führend, Marktführer, immer,
  nie, state of the art.
- **Mark estimates as estimates:** geschätzt, typischerweise, in der Regel.
  Never state a number we would not hold to in a contract.

### 23. The recurring message

dns builds on what the customer already runs, extends it, and embeds the result
in the existing IT landscape. Carry this point wherever it applies, phrased for
the context — e.g. „Anschluss an Ihre bestehende IT“, „Integration in Ihre
Systemlandschaft“, „Bestehendes bleibt erhalten“. State it as method, not as a
boast, and never paste the same phrasing twice.

### 24. German

- **Sie / Ihr / Ihre**, without exception. Never du.
- **Gender-neutral participles:** *Mitarbeitende, Nutzende*. No gender colon or
  star forms.
- **Percent with a space:** `80 %`.
- **Dashes:** one style per document, never mixed — the spaced en dash ( – ) or
  the em dash ( — ). dns has not settled on one yet; follow the surrounding
  material.

### 25. English

- **British spelling:** prioritised, organisation, modernised, analyse.
- **Sentence case** for headings: "What you receive".
- Keep **Mittelstand** untranslated.
- English is a **translation, not a rewrite**: same claims, same order, same
  number of items.

### 26. Fixed strings

- **dns** — lowercase in running text. Legal name: **digital nervous systems GmbH**.
- „seit 1999“ / since 1999. Nürnberg (EN: Nuremberg).
- Address: Krugstraße 12, 90419 Nürnberg.
- Phone: `+49 (911) 517 095-0`.

---

## Final checklist

**Visual**
- [ ] Only the brand colours; amber is the single accent and never darkened
- [ ] No text below 60 % on light / 45 % on dark
- [ ] Manrope for headings, Inter for everything else; display leading ≥ 1.1
- [ ] Light hero or title slide; nothing above any title except the two exceptions
- [ ] Square, flat surfaces; shadows only on floating elements
- [ ] At most one highlight per headline, light backgrounds only, never amber text
- [ ] Never two filled buttons side by side
- [ ] Logo untouched, correct version for the background; imagery calm and warm

**Code**
- [ ] No colour literal outside the token definitions
- [ ] Section spacing is one of the two values
- [ ] Every pattern used twice is one component
- [ ] Focus visible everywhere; reduced motion honoured; no entry motion on mobile

**Copy**
- [ ] Would a managing director forward it without editing a claim?
- [ ] At most one „nicht X, sondern Y“ per section
- [ ] Sie-form, no superlatives, estimates marked
- [ ] German and English changed together, same claims in the same order
