Design — Balancee Astro
The look of this Astro template comes from a small set of tokens: change one and nearly every page, component and state follows.
So you rarely need to touch a component. This guide covers the colours, the logo, the fonts, the text styles, the spacing, the motion, the components and the icons.
See everything first
Section titled “See everything first”Run npm run dev and open http://localhost:4321/style-guide. It shows the colours and text styles, the wordmark, the
buttons (hover them), the menu links and breadcrumbs, the section title, chips, stars, rating and figures, the cards
(service, post, case study, step, value, detail, figure, pillar, team, testimonial), the case study accordion, the video
cards, the About timeline and awards, the contact form with its states and the client logo ticker, each with its name.
When you want to know what a change will affect, look there.

Colours
Section titled “Colours”src/design-system/theme.css:
@theme { --color-ink: #121512; /* headings, the dark buttons, the active menu pill, the dark sections */ --color-text: #222222; /* the menu's links */ --color-grey: #5a5a5a; /* secondary text, meta */ --color-line: #e5e5e5; /* dividers, light fills */ --color-soft: #f5f5f5; /* the Client section, the blog cards */ --color-white: #ffffff; /* the page, text over dark */ --color-black: #000000;
--color-error: #d92d20; /* a form field that failed its check */ --color-danger: #ff2244; /* the form button when sending failed (a 15 % fill with this label) */ --color-field-line: rgb(136 136 136 / 0.1); /* the hairline of a form field */ --color-focus: #0099ff; /* the hairline of a focused text field */ --color-placeholder: rgb(47 47 47 / 0.5); /* a field's placeholder */ --color-dim: rgb(47 47 47 / 0.5); /* the year pills of the About timeline on black */}Each name becomes a Tailwind class: bg-ink, text-grey, border-line. Swap the hex values for your own palette and the
site changes. The template is near-black Ink on white with light grey (soft, line) panels: ink is the text, the
headings and the dark buttons, white the page and the text on dark, soft the panels and cards. Keep text on its
background at 4.5 : 1 or more, or the site becomes hard to read.
The footer, the About timeline and the client section use black and soft directly, and the photos’ covers are Tailwind
opacity classes (bg-black/80 over the hero video and the call-to-action band), so they follow black.
A few colours sit outside the tokens, so change them too when you change a colour:
| Colour | Where |
|---|---|
| The button tones (Ink and white, with the arrow’s colours) | src/design-system/components/actions/button.ts |
| The browser icons: the white “B” on Ink for a light browser theme, the Ink “B” on white for a dark one | public/icon-light.svg, public/icon-dark.svg, public/apple-icon.png |
| The client logos’ own colours | src/assets/images/client-logo-*.svg |
| The wordmark files | src/assets/images/logo.svg (Ink), logo-white.svg |
The logo is the text “Balancee” set in Inter (weight 600, letter spacing +4 %) by
src/design-system/components/brand/Wordmark.astro, in the current text colour. Logo.astro wraps it as the header’s
link to Home; the footer and the Home hero (in white, over the video) use Wordmark too. To use your own:
- As text: the word is written in
Wordmark.astro(>Balancee<at the end of the file): type your name. The box keeps a fixed size per place (139 × 25 px in the header, 111 × 20 on phones, 166 × 30 in the footer, 278 × 50 over the Home video): a long name may run past it, so change thesizesat the top of the file to fit. - As an SVG or an image file: replace the
<span>inWordmark.astrowith an<svg>or an<img>of your logo and keep the box sizes. A file has one colour, so check it on the white header, on the footer’s white strip and over the dark hero.
The logo’s name for screen readers is logo.alt in src/content/site.json. The same wordmark is in
src/assets/images/logo.svg and logo-white.svg for use elsewhere; the site itself draws the logo from Wordmark.astro.
The “B” icon
Section titled “The “B” icon”The browser icon is a white “B” on a rounded Ink square (public/icon-light.svg, shown in light browser themes) and its
inverse (public/icon-dark.svg, for dark themes). public/apple-icon.png (180 × 180) is the home screen icon. Replace the
three with your own mark; keep the file names and the sizes, or change the <link> lines in src/layouts/Layout.astro.
The template loads Inter with the Astro Fonts API, in astro.config.mjs:
fonts: [ { provider: fontProviders.google(), name: "Inter", cssVariable: "--font-inter", weights: ["100 900"], styles: ["normal"], subsets: ["latin"], fallbacks: ["Inter Fallback", "sans-serif"], optimizedFallbacks: false, },],Inter is one variable font here, every weight from 100 to 900; the site uses 400 (text) and 500 (headings, the menu and
the buttons), and 600 for the wordmark. The <Font> line in src/layouts/Layout.astro loads it on every page, and
theme.css makes --font-inter the site font (--font-sans). There is no italic in the template.
To use another Google font, change name and keep cssVariable:
name: "Manrope",cssVariable: "--font-inter",weights: ["200 800"],styles: ["normal"],Give a variable font its own range, or list ["400", "500", "600"] for a font that isn’t variable; a range the font doesn’t
have makes Google Fonts refuse the request, and the build warns No data found for font family … and leaves the site on
the fallback font. theme.css also defines Inter Fallback, Arial resized to Inter’s metrics so the page does not shift
when the font arrives: remove it from fallbacks (and its @font-face) when you change the font, or adjust its numbers.
For a font you have licensed yourself, use fontProviders.local() with your files, for example in src/assets/fonts/
(see the Astro fonts guide). Astro downloads the font when the site builds
and serves it from your own domain either way, so there is no request to Google at runtime.
Text styles
Section titled “Text styles”src/design-system/tokens/text.ts holds the sizes and line heights, named as in the original design:
| Style | Phone | Tablet (md:) |
Desktop (lg:) |
Used for |
|---|---|---|---|---|
h1 |
32 | 48 | 52 | The page titles |
h2 |
30 | 36 | 48 | Section titles |
h3 |
28 | 32 | 36 | The figures, rich-text headings |
h4 |
24 | 26 | 28 | Card titles |
h5 |
20 | 22 | 24 | Larger card text, the call-to-action band’s title |
h6 |
18 | 19 | 20 | Service names, small titles, the prompts |
paragraph |
16 | 16 | 16 | Leads, descriptions, rich text, the footer’s links |
small |
14 | 14 | 14 | Labels, meta, breadcrumbs |
tiny |
12 | 12 | 12 | The case study tags, the legal links, the line under the form |
eyebrow |
13 | 13 | 13 | Upper-case section labels such as “WHAT WE OFFER” |
button |
16 | 16 | 16 | Button labels |
Headings are weight 500 with a line height of 1.2; paragraph, small and tiny are weight 400 at 1.4; eyebrow is
weight 500 in upper case; button is weight 500 at 1.2. Letter spacing is normal. Change the numbers in text.ts rather
than in the components, and text stays consistent across the site. Use a style as class={text.h2} or combine:
class={cn(text.h6, "text-white")}.
Breakpoints and spacing
Section titled “Breakpoints and spacing”Three sizes, set in theme.css:
| Width | Tailwind prefix | |
|---|---|---|
| Phone | below 810 px | (none) |
| Tablet | 810–1199 px | md: |
| Desktop | 1200 px and up | lg: |
The side padding is 15 px on phones, 20 px on tablets and 30 px on desktops, and most sections have 60 / 80 / 100 px above
and below (sectionGutters and sectionPadding in src/design-system/components/layout/section.ts); the gap between a
section’s blocks is set per section (the gap prop of Section). Content is at most 1200 px wide (the header and footer
1440 px) and stays centred on wider screens. The header is fixed to the top, 60 px tall on phones, 71 px on tablets and 75
px on desktops (Pages and sections); <main> starts below a spacer of the same height
(src/layouts/Layout.astro).
Motion
Section titled “Motion”Balancee moves on hover, on click and in loops; nothing animates on load and nothing is tied to the scroll (the header
never changes while you scroll). src/design-system/tokens/motion.ts holds the springs the scripts play with Motion, and
theme.css holds the CSS curves and loops:
| Token | Values | Used for |
|---|---|---|
spring (S0) |
no bounce, 0.4 s | The case study accordion opening and closing, the phone menu growing, other changes the scripts play |
springSoft (S2) |
bounce 0.2, 0.4 s | The plus-minus marks |
cardTween |
0.4 s, an ease-in | The team card’s bio |
--ease-spring (CSS) |
spring with no bounce, use with duration-[450ms] |
The service and post cards: the photo frame loses its padding on hover |
--ease-card (CSS) |
0.4 s curve | The case study cards’ photo zooming on hover |
--animate-marquee (CSS) |
78 s, linear, loops | The client logo ticker (paused under the pointer) |
--animate-turn (CSS) |
1 s, linear, loops | The ring that spins while the Blog or the Portfolio loads more |
Hovers are CSS classes in the markup (group-hover:, transition): a button’s label rolls up and its arrow turns, a menu
link underlines, a card’s frame loosens. Lower a duration in motion.ts for a snappier feel, or raise bounce for a
livelier one. There are no page transitions and nothing counts up.
| Effect | Where to change it |
|---|---|
| The client logos sliding left | --animate-marquee in theme.css (the speed is the duration), LogoTicker.astro |
| The Home hero video, the About clip, the testimonial video | src/design-system/components/media/VideoPlayer.astro (mode: loop, view, click) and scripts/video-player.ts |
| The Portfolio and the Blog show four items, then four more as the end comes within 500 px | list.pageSize in portfolio.json and blog.json; scripts/load-on-scroll.ts |
| Home shows six services and three posts | services.count and blog.count in src/content/pages/home.json |
| A post ends with two other posts, a case study with two, a service with three | otherCount in blog.json (post), portfolio.json (detail) and service.json (detail) |
| The case study rows open and close on their own | src/design-system/components/patterns/CaseAccordion.astro and scripts/case-accordion.ts |
| The phone menu | src/components/site/header.ts and scripts/hamburger.ts |
Reduced motion
Section titled “Reduced motion”With “reduce motion” switched on in the visitor’s system, movement is left out: the logo ticker stands still, the Home hero
video and the About clip stay on their poster, and moves, turns and size changes jump. Colour changes and fades stay.
play() in src/design-system/utils/play.ts, which every script animates through, makes moves, turns and sizes jump; the
CSS loops check the setting with motion-reduce:.
Corners, spacing, shadows
Section titled “Corners, spacing, shadows”Corners are 10 px on cards, photos and tiles; 4 px on the footer’s white strip, the play pill and a few small boxes;
buttons and pills are fully round. There are no drop shadows. Spacing is Tailwind classes on the components (gap-5,
p-5, gap-[50px]). Tailwind’s scale is 4 px per step, so gap-5 is 20 px. Change them where you see them; the style
guide shows the result immediately.
Components
Section titled “Components”src/design-system/components/ holds the buttons and links (with the rolling label), the plus-minus box, the wordmark and
the icons, the menu button, the section layout with its title and breadcrumbs, the cards (service, post, case study, step,
value, detail, figure, pillar, team, testimonial), the chips, stars, rating, figures and timeline steps, the awards, the
case study accordion, the lists that load on scroll, rich text, the images, the video player and the logo ticker, and the
form parts. Their behaviour is in src/design-system/scripts/: each component with state calls an init*() function from
its own <script>. The README lists every component, and the sections that make up a
page are one level up, in src/components/sections/ (Pages and sections).
The icons are Phosphor shapes stored as path data in
src/design-system/components/icons/paths.ts: arrow-right, arrow-up-right, star-fill, plus, phone and
envelope. <Icon name="arrow-right" /> draws one in the current text colour. To add one:
-
Open the icon on phosphoricons.com and copy the SVG.
-
Take the
d="…"of its<path>. -
Add a line to
iconPaths:"my-icon": "M128,24A104,104,0,1,0,…",
Then use <Icon name="my-icon" class="size-5" />. Paths use a 256 × 256 grid, which is what Phosphor exports; an icon
drawn on another grid gets its viewBox in iconViewBoxes. The LinkedIn mark on the team cards is an image file
(src/assets/images/icon-linkedin.svg), set per card with iconSrc in src/components/sections/AboutTeam.astro.