Skip to content
Sign inJoin waitlist

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.

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.

The style guide page: the colours and text styles, then every component with its name

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 the sizes at the top of the file to fit.
  • As an SVG or an image file: replace the <span> in Wordmark.astro with 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 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.

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")}.

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).

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

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 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.

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:

  1. Open the icon on phosphoricons.com and copy the SVG.

  2. Take the d="…" of its <path>.

  3. 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.