# MFC Design System

Instructions for Claude Code. Read this whole file before designing or building any part of the MFC Modern Foundations website, then follow it exactly.

- Visual reference: https://mfc-kit.pages.dev/
- This file: https://mfc-kit.pages.dev/DESIGN.md
- Everything in one ZIP: https://mfc-kit.pages.dev/downloads/mfc-design-system.zip

## Start here

1. Download and unzip the ZIP into the project. It holds this file, the tokens, the glass CSS, logos, icons, website icons and the Latin font.
2. Open the visual reference and match it. If this file and the page disagree, this file wins.
3. Ask the user for two things, one time, with these links: the Thmanyah Sans files from https://font.thmanyah.com and the project photos from https://drive.google.com/drive/folders/1yEyvIJ0c7esGVSb1oBYN69ygPol3IXj1 . Never fetch the font from anywhere else. See "Arabic font licence".
4. Use tokens for every value. Do not invent colors, sizes, radii, shadows or spacing.
5. Build phone and laptop deliberately. Every value below is defined per device. Never reuse one size for both.

## Rules that never change

- Style: modern, minimal, soft, calm, with clear order.
- Corners: radius 0 on everything. Nothing is rounded.
- Shadows: none, anywhere.
- Buttons and the header are glass. No stroke and no shadow on them.
- Lines appear only in form fields, tables and the footer divider. Separate everything else with empty space.
- Never use boxes around text, a small label above every title, numbered sections, an icon beside every title, gradients, emoji, fake stats or filler quotes.
- Never pile text on top of text like slides. Few words, generous space.
- The emblem (connected MFC alone) is the main logo. The full logo with Modern Foundations is for rare use.
- White keeps the two dark colors apart. Never put navy directly against black.

## Word limits

| Item | Maximum |
|---|---|
| Hero title | 6 words |
| Section title | 5 words |
| Section text | 20 words |
| Button | 3 words |
| Items in a row | 4 |

## Files

| Item | URL |
|---|---|
| Everything | https://mfc-kit.pages.dev/downloads/mfc-design-system.zip |
| Tokens JSON | https://mfc-kit.pages.dev/downloads/mfc.tokens.json |
| Tokens CSS | https://mfc-kit.pages.dev/downloads/mfc-tokens.css |
| Glass CSS | https://mfc-kit.pages.dev/downloads/mfc-glass.css |
| Latin font | https://mfc-kit.pages.dev/fonts/GoogleSansFlex-Latin.woff2 |
| Arabic font | https://font.thmanyah.com (official site only) |
| Logos ZIP | https://mfc-kit.pages.dev/downloads/mfc-logos.zip |
| Icons ZIP | https://mfc-kit.pages.dev/downloads/mfc-icons.zip |
| Website icons ZIP | https://mfc-kit.pages.dev/downloads/mfc-website-icon.zip |
| Project photos | https://drive.google.com/drive/folders/1yEyvIJ0c7esGVSb1oBYN69ygPol3IXj1 |
| Mfc Logo Primary | https://mfc-kit.pages.dev/logo/mfc-logo-primary.svg |
| Mfc Logo Reversed | https://mfc-kit.pages.dev/logo/mfc-logo-reversed.svg |
| Mfc Mark Black | https://mfc-kit.pages.dev/logo/mfc-mark-black.svg |
| Mfc Mark Navy | https://mfc-kit.pages.dev/logo/mfc-mark-navy.svg |
| Mfc Mark White | https://mfc-kit.pages.dev/logo/mfc-mark-white.svg |
| favicon.ico | https://mfc-kit.pages.dev/website-icon/favicon.ico |
| icon.svg | https://mfc-kit.pages.dev/website-icon/icon.svg |
| apple-touch-icon.png | https://mfc-kit.pages.dev/website-icon/apple-touch-icon.png |
| icon-192.png | https://mfc-kit.pages.dev/website-icon/icon-192.png |
| icon-512.png | https://mfc-kit.pages.dev/website-icon/icon-512.png |
| icon-mask.png | https://mfc-kit.pages.dev/website-icon/icon-mask.png |

## Tokens

Use this CSS as the base. JSON version: https://mfc-kit.pages.dev/downloads/mfc.tokens.json

```css
/* MFC tokens. Phone values first, laptop from 840 px. Set data-theme on <html>. */
:root {
  color-scheme: light;
  --mfc-bg: #FFFFFF;
  --mfc-surface: #F4F4F5;
  --mfc-surface-2: #EAEAEC;
  --mfc-fg: #0E0F11;
  --mfc-text: #65676B;
  --mfc-border: #8C8C8C;
  --mfc-line: #E6E6E8;
  --mfc-accent: #011E53;
  --mfc-on-accent: #FFFFFF;
  --mfc-error: #B42318;
  --mfc-success: #0F6B3E;
  --mfc-navy-50: #F2F5FB;
  --mfc-navy-100: #E2E8F3;
  --mfc-navy-200: #C7D2E3;
  --mfc-navy-300: #A2B2CC;
  --mfc-navy-400: #788DB0;
  --mfc-navy-500: #516993;
  --mfc-navy-600: #314D7B;
  --mfc-navy-700: #193668;
  --mfc-navy-800: #011E53;
  --mfc-space-4: 4px;
  --mfc-space-8: 8px;
  --mfc-space-12: 12px;
  --mfc-space-16: 16px;
  --mfc-space-24: 24px;
  --mfc-space-32: 32px;
  --mfc-space-40: 40px;
  --mfc-space-48: 48px;
  --mfc-space-64: 64px;
  --mfc-space-80: 80px;
  --mfc-space-120: 120px;
  --mfc-display-size: 44px;
  --mfc-display-line: 48px;
  --mfc-h1-size: 36px;
  --mfc-h1-line: 40px;
  --mfc-h2-size: 28px;
  --mfc-h2-line: 32px;
  --mfc-h3-size: 22px;
  --mfc-h3-line: 28px;
  --mfc-h4-size: 18px;
  --mfc-h4-line: 24px;
  --mfc-lead-size: 16px;
  --mfc-lead-line: 24px;
  --mfc-body-size: 16px;
  --mfc-body-line: 24px;
  --mfc-small-size: 14px;
  --mfc-small-line: 20px;
  --mfc-label-size: 14px;
  --mfc-label-line: 20px;
  --mfc-button-size: 15px;
  --mfc-button-line: 20px;
  --mfc-caption-size: 12px;
  --mfc-caption-line: 16px;
  --mfc-ar-display-size: 44px;
  --mfc-ar-display-line: 56px;
  --mfc-ar-h1-size: 36px;
  --mfc-ar-h1-line: 48px;
  --mfc-ar-h2-size: 28px;
  --mfc-ar-h2-line: 36px;
  --mfc-ar-h3-size: 22px;
  --mfc-ar-h3-line: 32px;
  --mfc-ar-h4-size: 18px;
  --mfc-ar-h4-line: 28px;
  --mfc-ar-lead-size: 16px;
  --mfc-ar-lead-line: 28px;
  --mfc-ar-body-size: 16px;
  --mfc-ar-body-line: 28px;
  --mfc-ar-small-size: 14px;
  --mfc-ar-small-line: 24px;
  --mfc-ar-label-size: 14px;
  --mfc-ar-label-line: 20px;
  --mfc-ar-button-size: 15px;
  --mfc-ar-button-line: 20px;
  --mfc-ar-caption-size: 12px;
  --mfc-ar-caption-line: 20px;
  --mfc-font-ar: 'Thmanyah Sans', system-ui, sans-serif;
  --mfc-radius: 0;
  --mfc-margin: 16px;
  --mfc-gutter: 16px;
  --mfc-section: 64px;
  --mfc-header: 56px;
  --mfc-button: 44px;
  --mfc-font: 'Google Sans Flex', system-ui, sans-serif;
}
@media (min-width: 840px) {
  :root {
    --mfc-display-size: 72px;
    --mfc-display-line: 76px;
    --mfc-h1-size: 56px;
    --mfc-h1-line: 60px;
    --mfc-h2-size: 40px;
    --mfc-h2-line: 44px;
    --mfc-h3-size: 28px;
    --mfc-h3-line: 36px;
    --mfc-h4-size: 20px;
    --mfc-h4-line: 28px;
    --mfc-lead-size: 18px;
    --mfc-lead-line: 28px;
    --mfc-body-size: 16px;
    --mfc-body-line: 24px;
    --mfc-small-size: 14px;
    --mfc-small-line: 20px;
    --mfc-label-size: 14px;
    --mfc-label-line: 20px;
    --mfc-button-size: 14px;
    --mfc-button-line: 20px;
    --mfc-caption-size: 12px;
    --mfc-caption-line: 16px;
    --mfc-ar-display-size: 72px;
    --mfc-ar-display-line: 88px;
    --mfc-ar-h1-size: 56px;
    --mfc-ar-h1-line: 72px;
    --mfc-ar-h2-size: 40px;
    --mfc-ar-h2-line: 52px;
    --mfc-ar-h3-size: 28px;
    --mfc-ar-h3-line: 40px;
    --mfc-ar-h4-size: 20px;
    --mfc-ar-h4-line: 32px;
    --mfc-ar-lead-size: 18px;
    --mfc-ar-lead-line: 32px;
    --mfc-ar-body-size: 16px;
    --mfc-ar-body-line: 28px;
    --mfc-ar-small-size: 14px;
    --mfc-ar-small-line: 24px;
    --mfc-ar-label-size: 14px;
    --mfc-ar-label-line: 20px;
    --mfc-ar-button-size: 14px;
    --mfc-ar-button-line: 20px;
    --mfc-ar-caption-size: 12px;
    --mfc-ar-caption-line: 20px;
    --mfc-margin: 48px;
    --mfc-gutter: 32px;
    --mfc-section: 120px;
    --mfc-header: 72px;
    --mfc-button: 40px;
    --mfc-page: 1216px;
    --mfc-content: 1120px;
  }
}
[data-theme="dark"] {
  color-scheme: dark;
  --mfc-bg: #000000;
  --mfc-surface: #15171A;
  --mfc-surface-2: #22242A;
  --mfc-fg: #FFFFFF;
  --mfc-text: #A6A8AD;
  --mfc-border: #75787E;
  --mfc-line: #26282C;
  --mfc-accent: #FFFFFF;
  --mfc-on-accent: #011E53;
  --mfc-error: #FF8A7A;
  --mfc-success: #5FD39A;
}
```

## Color

Balance: White 70, Navy 20, Black 10.

| Name | Value |
|---|---|
| MFC Navy | #011E53 |
| Black | #000000 |
| White | #FFFFFF |
| Ink | #0E0F11 |
| Text | #65676B |
| Border | #8C8C8C |
| Line | #E6E6E8 |
| Surface | #F4F4F5 |
| Error | #B42318 |
| Success | #0F6B3E |
| Surface 2 | #EAEAEC |

Navy scale:

| Step | Value |
|---|---|
| 50 | #F2F5FB |
| 100 | #E2E8F3 |
| 200 | #C7D2E3 |
| 300 | #A2B2CC |
| 400 | #788DB0 |
| 500 | #516993 |
| 600 | #314D7B |
| 700 | #193668 |
| 800 | #011E53 |

Allowed pairs:

| Pair | Text | Ground | Contrast |
|---|---|---|---|
| Ink on white | #0E0F11 | #FFFFFF | 19.2:1 |
| Text on white | #65676B | #FFFFFF | 5.7:1 |
| Navy on white | #011E53 | #FFFFFF | 16.0:1 |
| White on navy | #FFFFFF | #011E53 | 16.0:1 |
| Soft on navy | #99A5BA | #011E53 | 6.4:1 |
| White on black | #FFFFFF | #000000 | 21.0:1 |

Never use:

| Pair | Text | Ground | Contrast |
|---|---|---|---|
| Navy on black | #011E53 | #000000 | 1.3:1 |
| Black on navy | #000000 | #011E53 | 1.3:1 |
| Text on navy | #65676B | #011E53 | 2.8:1 |
| Text on black | #65676B | #000000 | 3.7:1 |
| Error on navy | #B42318 | #011E53 | 2.4:1 |
| White on line | #FFFFFF | #E6E6E8 | 1.2:1 |

## Light and dark

Every token has both values. Set `data-theme` on `<html>`, and offer a clear Light and Dark switch.

| Token | Light | Dark |
|---|---|---|
| bg | #FFFFFF | #000000 |
| surface | #F4F4F5 | #15171A |
| surface-2 | #EAEAEC | #22242A |
| fg | #0E0F11 | #FFFFFF |
| text | #65676B | #A6A8AD |
| border | #8C8C8C | #75787E |
| line | #E6E6E8 | #26282C |
| accent | #011E53 | #FFFFFF |
| on-accent | #FFFFFF | #011E53 |
| error | #B42318 | #FF8A7A |
| success | #0F6B3E | #5FD39A |

## Typography

Latin font: Google Sans Flex. https://mfc-kit.pages.dev/fonts/GoogleSansFlex-Latin.woff2 or https://fonts.google.com/specimen/Google+Sans+Flex

Weights are distributed. Never use one weight everywhere: the larger the size, the lighter the weight.

| Style | Laptop size / line | Phone size / line | Weight | Tracking |
|---|---|---|---|---|
| Display | 72 / 76 | 44 / 48 | Light 300 | −3% |
| H1 | 56 / 60 | 36 / 40 | Light 300 | −3% |
| H2 | 40 / 44 | 28 / 32 | Regular 400 | −2.5% |
| H3 | 28 / 36 | 22 / 28 | Regular 400 | −2% |
| H4 | 20 / 28 | 18 / 24 | Medium 500 | −1% |
| Lead | 18 / 28 | 16 / 24 | Light 300 | 0 |
| Body | 16 / 24 | 16 / 24 | Regular 400 | 0 |
| Small | 14 / 20 | 14 / 20 | Regular 400 | 0 |
| Label | 14 / 20 | 14 / 20 | Medium 500 | 0 |
| Button | 14 / 20 | 15 / 20 | Medium 500 | 0 |
| Caption | 12 / 16 | 12 / 16 | Semibold 600 | +8% |

- Line length: 66 characters, limit 45 to 90.
- Align left in English. Never justify.
- Capitals: under one line only.
- Curly quotes. One space after a period.
- One H1 on each page. No skipped levels.

## Arabic

Arabic pages use `dir="rtl"` and mirror the layout. Use CSS logical properties. Do not mirror the logo, photos or numbers. Arrows flip.

Arabic font: Thmanyah Sans. Weights Light 300, Regular 400, Medium 500, Bold 700. Set tracking to 0 at every size. Never use letter spacing or capitals rules on Arabic.

| Style | Laptop size / line | Phone size / line | Weight |
|---|---|---|---|
| Display | 72 / 88 | 44 / 56 | Light 300 |
| H1 | 56 / 72 | 36 / 48 | Light 300 |
| H2 | 40 / 52 | 28 / 36 | Regular 400 |
| H3 | 28 / 40 | 22 / 32 | Regular 400 |
| H4 | 20 / 32 | 18 / 28 | Medium 500 |
| Lead | 18 / 32 | 16 / 28 | Light 300 |
| Body | 16 / 28 | 16 / 28 | Regular 400 |
| Small | 14 / 24 | 14 / 24 | Regular 400 |
| Label | 14 / 20 | 14 / 20 | Medium 500 |
| Button | 14 / 20 | 15 / 20 | Medium 500 |
| Caption | 12 / 20 | 12 / 20 | Bold 700 |

Write Arabic copy in Modern Standard Arabic.

### Arabic font licence

Official download only: https://font.thmanyah.com

The licence forbids redistributing, uploading, hosting or offering the font files for download anywhere, and forbids exposing them so third parties can extract them. It allows use on websites only as part of a compiled, packaged or obfuscated product. So:

- Do not commit the font files to a public repository.
- Do not place them at a public URL as plain files.
- Ask the user to download them from the official site and supply them locally.
- Before launch, confirm the web embedding method with ask@thmanyah.com.

## Spacing

Base 8. Allowed steps: 4, 8, 12, 16, 24, 32, 40, 48, 64, 80, 120.

| Use | Laptop | Phone |
|---|---|---|
| Page margin | 48 | 16 |
| Gutter | 32 | 16 |
| Between sections | 120 | 64 |
| Heading to content | 64 | 40 |
| Between groups | 32 | 24 |
| Heading to text | 24 | 16 |
| Between items | 16 | 12 |
| Inside a group | 8 | 8 |

Space above a heading is about twice the space below it.

## Grid

| | Laptop | Phone |
|---|---|---|
| Width | 840 and up | Up to 839 |
| Columns | 12 | 4 |
| Column | 64 | Fluid |
| Gutter | 32 | 16 |
| Margin | 48 | 16 |
| Content width | 1120 | Full |
| Page width | 1216 | Full |

Common laptop layouts: 12, 6 + 6, 4 + 4 + 4, 3 + 3 + 3 + 3, 8 + 4. Common phone layouts: 4, 2 + 2.

## Logo

Files are cropped exactly to the logo, so add clear space in the layout.

- Clear space: 4x on every side, where x is the stroke of the M. Formula: emblem width × 0.224.
- Header emblem: 72 wide on laptop, 56 wide on phone.
- Navy on white. White on navy or black. Never recolor, stretch or add effects.

## Website icon

Navy on white, white on black. `icon.svg` switches by itself.

```html
<link rel="icon" href="/favicon.ico" sizes="32x32">
<link rel="icon" href="/icon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
```

## Icons

Phosphor Regular only. Starter set in the ZIP. Get others from https://phosphoricons.com/?weight=regular

Icon size 24. Tap area 44 on laptop, 48 on phone.

## Glass

Used only on the header and buttons. Sharp corners, no stroke, no shadow.

```css
/* MFC Glass. Sharp corners. No stroke. No shadow. */
:root {
  --glass-bg: rgba(238, 241, 246, .62);
  --glass-tint: rgba(1, 30, 83, .62);
  --glass-tint-hover: rgba(1, 30, 83, .78);
  --glass-light: rgba(255, 255, 255, .28);
}
[data-theme="dark"] {
  --glass-bg: rgba(38, 40, 46, .68);
  --glass-tint: rgba(255, 255, 255, .66);
  --glass-tint-hover: rgba(255, 255, 255, .82);
  --glass-light: rgba(255, 255, 255, .12);
}
.glass {
  position: relative;
  overflow: hidden;
  isolation: isolate;
  background: var(--glass-bg);
  border: 0;
  border-radius: 0;
  box-shadow: none;
  -webkit-backdrop-filter: blur(20px) saturate(180%);
  backdrop-filter: blur(20px) saturate(180%);
  transition: background .5s cubic-bezier(.22, .61, .36, 1);
}
.glass.tint { background: var(--glass-tint); }
.glass::after {
  content: "";
  position: absolute;
  inset: 0;
  z-index: -1;
  pointer-events: none;
  opacity: 0;
  transition: opacity .5s cubic-bezier(.22, .61, .36, 1);
  background: radial-gradient(140px 70px at var(--mx, 50%) var(--my, 0%), var(--glass-light), transparent 70%);
}
.glass:hover::after { opacity: 1; }
a.glass.tint:hover, button.glass.tint:hover, .glass.tint.is-hover { background: var(--glass-tint-hover); }
@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
  .glass { background: var(--surface); }
  .glass.tint { background: var(--accent); }
}
```

```js
// The light on the glass follows the pointer.
document.querySelectorAll('.glass').forEach(function (el) {
  el.addEventListener('pointermove', function (e) {
    var box = el.getBoundingClientRect();
    el.style.setProperty('--mx', (e.clientX - box.left) + 'px');
    el.style.setProperty('--my', (e.clientY - box.top) + 'px');
  });
});
```

## Components

| Component | Laptop | Phone |
|---|---|---|
| Header | 72 high, glass, emblem left, up to 5 links, button right | 56 high, glass, emblem, menu icon |
| Primary button | Glass tint, 40 high, 20 padding, 14 / Medium, fit text | Glass tint, 44 high, 15 / Medium, full width |
| Secondary button | Clear glass, same sizes | Clear glass, same sizes |
| Icon button | 40 square | 44 square |
| Disabled button | Solid `line` color, no glass | Same |
| Link | 14 to 15 / Medium, accent, arrow | Same |
| Text field | 48 high, 1 px border, 16 text, label above | 52 high, otherwise same |
| Form | 2 columns, 24 gap | 1 column, 24 gap |
| Checkbox, radio, switch | Sharp shapes, 44 tap height | Same |
| Error | Red border, short message below | Same |
| Hero | 720 high, photo with navy at 50%, H1 Light bottom left, one button | 640 high, H1 36 / 40, full width button |
| Project cards | 4 in a row, gap 16, 9:16 image, name below | 2 in a row, gap 8 |
| Field list | 5 in a row, icon and name | Stacked |
| Tabs | Surface fill on active, no underline | Scroll sideways |
| Breadcrumb | Full path | Back link only |
| Pagination | Numbers and arrows | Current page and arrows |
| Accordion | Surface fill, no lines, 56 high | Same |
| Modal | Centered, 480 wide, navy veil at 45% | Bottom sheet, full width |
| Alert | One short line, icon carries the color | Same |
| Tag | 28 high, square | Same |
| Tooltip | On hover | None |
| Table | Lines between rows only | Stacked items |
| Loading | Progress bar and square skeleton blocks, no spinners | Same, one column |
| Empty state | Icon, one line, one link | Same |
| Footer | Navy in both modes, 3 columns | Navy, 1 column |

## Images

Project photos: https://drive.google.com/drive/folders/1yEyvIJ0c7esGVSb1oBYN69ygPol3IXj1

Use real project photos. Use only the listed shapes: 16:9, 9:16 and 1:1, with square corners.

## Writing

Calm, clear, confident. Short sentences. Sentence case in headings. Use "MFC Modern Foundations" first, then "MFC".

Fields, in this order: Construction, Contracting, Finishing, FF&E, Real estate.

## Before you finish

Check each page on both devices against this list: tokens only, radius 0, no shadows, lines only where allowed, weights distributed, word limits kept, navy never against black, light and dark both correct.