CSS and icons

Your styles

Use site/css/theme.css for colors, fonts, and spacing tokens. Put shared rules inside the existing @layer styles block in site/css/global.css:

a {
  text-underline-offset: .2em;
}

h1 {
  color: var(--brand-1);
}

Save while dev is running to see the changes. Normal deployment publishes your committed CSS.

Prewind utilities

Prewind is a CSS library with a reset and utility classes for layout, spacing, and color. The generated site includes version 1.3.1. We recommend it for its shared defaults and fluid spacing and type scales: you can style familiar HTML with a single stylesheet.

Your CSS, your choice. You can remove Prewind and use plain CSS or any styling library you like. Prewind works especially well with Itsy because neither needs a build step.

Prewind's fluid spacing and type scales adapt to the screen width. Theme tokens keep those sizes and your colors consistent across the site, and you can change them in site/css/theme.css.

<section class="container py-xl">
  <h1>Visit the bookshop</h1>
  <p class="text-lg">Find your next read.</p>
</section>

container provides the page width and padding. Sizes such as sm, md, and lg follow the theme's fluid scale.

Use your own styling

Prewind is optional. To use plain CSS or another styling library, replace the stylesheet link in site/main.layout.html with your own:

<link rel="stylesheet" href="/css/my-styles.css" />

If you want to keep the starter's other styles, leave the layout link in place and remove just this import from site/css/global.css:

@import url("https://unpkg.com/prewindcss@1.3.1");

Update the starter's utility classes and any CSS that depends on Prewind's tokens or reset to suit your replacement. Check other layouts, including site/admin.layout.html, if you want them to use it too. Itsy works with whichever styling approach you choose.

Lucide icons

Lucide icon support is built in. Browse and search the Lucide icon picker, choose an icon, then use its lowercase, hyphenated name in a page, layout, or partial:

{icon arrow-right}
{icon search size="20" aria-label="Search"}

Itsy renders each icon as inline SVG. You don't need an icon script or package installation. Icons default to 24 × 24, with no fill and a 2px stroke that inherits the surrounding text color.

Supported options

Use quoted attributes, with either single or double quotes:

{icon check size="20" stroke-width="3" class="text-brand-1"}
{icon info aria-label="About {page.title}"}

Attribute values can include dotted-path data, as in aria-label="About {page.title}", including aliases inside loops. The icon name itself must be literal. Dynamic names, custom icon sources, inline style, event handlers, and href are unsupported. Use a CSS class to style an icon and wrap it in an ordinary link or button when needed.

Accessible icons

Icons are decorative by default and hidden from screen readers with aria-hidden="true". Keep that default beside visible text. For an icon that conveys meaning on its own, add aria-label or aria-labelledby. For an icon-only button, label the button itself:

<button type="button" aria-label="Search">
  {icon search size="20"}
</button>

Downloads and offline use

itsy dev downloads only the icons you reference into itsy/icons/, including new references when you save. Commit that cache so the site can use them offline. The browser uses the rendered SVG without making icon downloads.

Itsy currently uses Lucide 1.47.0, so icons added to the picker in newer releases may be unavailable. A missing icon is omitted and dev prints a warning. Check the name or connection, then save the template again to retry. itsy status reports missing icons but does not download them.

The {icon} directive supports Lucide. You can use other icon sets through your own HTML or SVG.