Design — Marai Neesu 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 font, 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, the text styles, the springs, the
buttons and links, the logo and the icons, the navigation, the layout, the cards, the status chip, the patterns (the
questions, the course modules, the tickers, the rolling roles, rich text) and the forms with their states, 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-black: #050505; /* text, the filled buttons; Black 80, 60, 30, 10, 05, 03 are black/80 … black/3 */ --color-grey: #9fa0a3; /* meta text, small labels, the phone menu button's lines */ --color-accent: #fc5000; /* hovers: titles, links, the e-mail's rolling copy, the Accent button, the stars */ --color-background: #f6f6f6; /* the page, the header, the text on black buttons */ --color-white: #ffffff; /* text over the course cover; White 50 is the pills of the desktop header */ --color-available: #1fb514; /* the dot of the CV's "Available for work" chip */ --color-error: #ff2244; /* the Submit button's fill after a failed send, at 15 % */}Each name becomes a Tailwind class: bg-accent, text-grey, text-black/80. Swap the hex values for your own
palette and the site changes. Most surfaces are Black at a low opacity on the Background (the cards are black/3 with a
black/5 hairline), so the palette stays two colours and an accent. Keep text on its background at 4.5 : 1 or more,
or the site becomes hard to read: Black on Background is about 18.9 : 1 in the demo, Black 80 about 11.4 : 1 and
Black 60 about 5.4 : 1, while Grey on Background is about 2.4 : 1, which is why the demo keeps Grey for small labels
next to darker text. Accent text on the Background (the Accent button, a hovered title) is about 3.1 : 1, enough for
large or bold text; pick a darker accent if you use it for body text.
A few colours sit outside the tokens, so change them too when you change a colour:
| Colour | Where |
|---|---|
| The header bar’s background (the Background, and transparent while the desktop page scrolls down) | rgba(246,246,246,1) in src/components/site/Header.astro and the two values in src/components/site/header.ts |
| The buttons’ hover states: the Outline button turning Black with Background text, the shadows of the Primary and Accent buttons | src/design-system/components/actions/button.ts |
| The product cards’ buy and details buttons on hover | src/design-system/components/actions/product-button.ts |
| The soft shadows of the post, service and tool cards on hover | PostCard.astro, ServiceCard.astro, ToolCard.astro in src/design-system/components/cards/ |
| The box of an open question (Black with a Background minus) | src/design-system/components/patterns/Accordion.astro and src/design-system/scripts/accordion.ts |
| The swatches of the style guide repeat the hex values as text | src/components/style-guide/tokens.ts |
These are written as rgb() / rgba() values of Black (5,5,5), Background (246,246,246) and Accent
(252,80,0), because the scripts animate between two exact colours; search for them when you change one of the three.
The logo is you: your round photo, your name and your city, linking home. src/design-system/components/brand/Logo.astro
draws it from person in src/content/site.json (Editing the content):
- On desktops it sits on a White 50 pill with a blur, with a verified seal after the name. While the pointer is over
it, the name and the place give way to the two
hoverLines(“Back to” / “Homepage”) and the seal to a round back arrow, at once. - On tablets and phones the photo, the name and the place sit on the bar, with no seal and no hover.
To show a wordmark instead, replace the contents of the <a> in Logo.astro with your SVG or an <img> of a file in
public/ (keep the link and give the image your name as its alt). The header calls the logo twice (the plain one and
the desktop pill), so one change covers both. Delete verifiedLabel and the seal if you don’t want the seal.
The browser icons are public/icon.png (64 × 64) and public/apple-icon.png (180 × 180).
The template loads Manrope with the Astro Fonts API, in astro.config.mjs:
fonts: [ { provider: fontProviders.google(), name: "Manrope", cssVariable: "--font-manrope", weights: ["200 800"], styles: ["normal"], subsets: ["latin"], fallbacks: ["sans-serif"], },],Manrope is one variable font here, every weight from 200 to 800. The site uses three: 400 for the displays and the
paragraphs, 500 for the headings, labels and buttons, and 700 for bold words in rich text. The <Font> line in
src/layouts/Layout.astro loads it on every page, and theme.css makes --font-manrope the site font
(--font-sans).
To use another Google font, change name and keep cssVariable:
name: "DM Sans",cssVariable: "--font-manrope",weights: ["100 1000"],styles: ["normal"],Give a variable font its own range (["100 1000"] for DM Sans), or list ["400", "500", "700"] for a font that isn’t
variable. A name Google Fonts doesn’t know makes the build warn No data found for font family … and leaves the site
on the fallback font. 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 15 text styles, named as in the original design:
| Style | Phone | Tablet (md:) |
Desktop (lg:) |
Used for |
|---|---|---|---|---|
display1 |
38 | 52 | 64 | The Home hero’s title |
display2 |
24 | 36 | 42 | A post’s title, the 404’s title |
h1 |
24 | 26 | 28 | The title of every other page, the course’s title, the footer’s call to action |
h2 |
22 | 24 | 26 | Section titles (“My latest work”, “Project Overview”, “Overview”) |
h3 |
20 | 22 | 24 | The custom-request row, the newsletter, the course’s blocks, post headings |
h4 |
20 | 21 | 22 | The CV’s block titles, the footer’s links, the course banner’s title |
h5 |
18 | 19 | 20 | Service, product and job titles, the questions, product headings |
h6 |
16 | 17 | 18 | Card titles, the greeting, the footer’s column titles |
h6Small |
14 | 14 | 14 | The logo’s name, the meta labels |
big |
18 | 18 | 18 | Leads of list pages, a post’s text |
paragraph |
16 | 16 | 16 | Descriptions, rich text, the footer’s links |
small |
14 | 14 | 14 | Meta, labels, the rolling roles |
tiny |
12 | 12 | 12 | The logo’s place |
menu |
13 | 13 | 13 | The header’s links |
button |
12 | 12 | 12 | Button labels, in capitals |
Everything is Manrope: the displays and paragraphs at weight 400, the headings, menu and button at 500. The headings
and the displays have a line height of 1.2; big and paragraph 1.4. 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-black/60")}.
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: |
Content is at most 1200 px wide, centred on wider windows. The side padding is 20 px on phones, 30 px on tablets and
40 px on desktops; sections have 40 / 50 / 50 px above and below and 50 px between their blocks (sectionGutters,
sectionPadding and sectionGap in src/design-system/components/layout/section.ts). A thin line (<Divider />)
separates most sections. The fixed header is 74 px tall on phones, 84 px on tablets and 92 px on desktops;
src/layouts/Layout.astro pads <main> by that (Pages and sections).
Motion
Section titled “Motion”src/design-system/tokens/motion.ts holds the springs, named as measured on the original design. The scripts in
src/design-system/scripts/ (and the header’s, src/components/site/header.ts) play them with Motion:
| Token | Values | Used for |
|---|---|---|
spring (S1) |
bounce 0.2, 0.4 s | Nearly every hover: the buttons, the menu links, the logo, the social tiles, the post and service cards, the menu button’s lines turning into a cross, the course modules |
springFlat (S2) |
no bounce, 0.4 s | The header’s scroll look and the phone menu, the project and product cards, the questions opening |
springRoll (S3) |
no bounce, 0.5 s | The e-mail in the Home hero rolling up to its Accent copy |
slideSpring (SL) |
stiffness 200, damping 40 | The rolling roles under the greeting and the testimonial slideshow on phones |
instant |
no animation | An underline that snaps back when the pointer leaves |
theme.css holds what runs in CSS: --ease-form (the colours of a form’s button, 0.2 s), --animate-turn (its
spinner, one turn a second) and the tickers’ keyframes. Lower a spring’s duration for a snappier feel, or raise
bounce for a livelier one.
Hovers are attributes in the markup, played by src/design-system/scripts/hover.ts: data-hover marks the element you
point at, data-motion gives each part that changes its two states (rest and hover), and data-transition names the
token it moves with (spring, flat, roll or instant). A part without data-transition moves with spring.
| Effect | Where to change it |
|---|---|
| The desktop header fades its background, the logo and the button away after the page moves 4 px down, and brings them back 4 px up | src/components/site/header.ts |
| The roles under the greeting change every 4 seconds | interval on <WordRoll> (4 when left out) in HomeHeroSection.astro and CvSection.astro |
| The testimonials move 10 px a second (tablets and desktops) | speed={10} on <Ticker> in src/components/sections/TestimonialsSection.astro |
| The testimonial slideshow on phones moves on every 4 seconds | 4000 in src/design-system/scripts/card-slideshow.ts |
| The client logos move 20 px a second | speed={20} on <Ticker> in src/components/sections/ClientsSection.astro |
| A service card’s photos roll 5 px a second, while the pointer is over the card (always on phones) | SPEED in src/design-system/components/cards/ServiceCard.astro |
| The Blog shows six posts, then the rest behind “Load More” | pageSize in src/content/pages/blog.json |
| The first question starts open | defaultOpen on <Accordion> (a list of row numbers from 0; [0] when left out) in FaqSection.astro |
| The first course module starts open | defaultOpen={index === 0} on <CourseModule> in CourseSection.astro |
There are no scroll-in effects: the blocks are in place as the page loads, as on the original design.
Reduced motion
Section titled “Reduced motion”With “reduce motion” switched on in the visitor’s system, movement is left out: the tickers stand still, the panels of
the questions and the modules open at once, and moves, turns and size changes jump to their end. Fades and colour
changes stay. play() in src/design-system/utils/play.ts, which every script animates through, makes the moves jump;
the tickers check the setting in CSS. The rolling roles and the slideshow on phones keep changing, as on the original,
but jump instead of sliding.
Corners, spacing, shadows
Section titled “Corners, spacing, shadows”Corners are 10 px on the cards, the photos and the newsletter box, and 8 px on the testimonial cards and the course
banner. Buttons, the header’s pills, the avatar and the arrows of the slideshow are round. Shadows are few: the Primary button lifts on hover, the post, service and tool cards get a soft shadow on hover,
and the Go Back button is always lifted. 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 (actions/), the logo (brand/), the cards (project,
product, post, service, testimonial, tool, job, CV lines, the course banner and module), the status chip (data/), the
form parts (forms/), the icons, the section layout and its title and divider (layout/), the images (media/), the
breadcrumbs and the social tiles (navigation/), the patterns (the questions, rich text, the ticker, the rolling words)
and two small utilities (the current year, the local time). Their behaviour is in src/design-system/scripts/: each
component with state calls an init*() function from its own <script>. The shapes they take are in
src/design-system/types.ts, and the README lists every component with its props and
every script with what it does. The sections that make
up a page are one level up, in src/components/sections/, and are listed in
Pages and sections.
The 14 icons (the Phosphor shapes the design uses, the Framer mark of the course label
included) are stored as path data in src/design-system/components/icons/paths.ts; <Icon name="arrow-up-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. If you
keep the style guide, add the new name to icons in src/components/style-guide/tokens.ts too: that list is
exhaustive on purpose, so npm run check reports it until you do.