Getting started

Talos UI ships in three layers — take what you need. The CSS layer needs no build step; the web components add a single module script; the Astro wrappers are pure developer-experience sugar on top.

Which layer when

Install

bun add @shelfwood/talos-ui

Astro

CSS layer only:

---
import "@shelfwood/talos-ui/talos.css";
---
<div class="glass-panel interactive-panel">
  <div class="glass-panel-content talos-pad"><h2>Hello</h2></div>
</div>

With the Astro wrappers (recommended on Astro):

---
import "@shelfwood/talos-ui/talos.css";
import GlassPanel from "@shelfwood/talos-ui/astro/GlassPanel.astro";
import Button from "@shelfwood/talos-ui/astro/Button.astro";
---
<GlassPanel as="a" href="/work"><h2>Projects</h2></GlassPanel>
<Button href="/contact">Get in touch</Button>

With web components (notched panels + instruments):

---
import "@shelfwood/talos-ui/talos.css";
---
<script>import "@shelfwood/talos-ui/wc";</script>

<talos-panel panel-width="400" panel-height="220">
  <talos-corner edge="top-right" radius="22"></talos-corner>
  <talos-notch edge="top" width="80" depth="14"></talos-notch>
  <h3>Composable geometry</h3>
</talos-panel>

Plain HTML

Point the stylesheet at the package under node_modules (dev) or a copy you vendor into your public assets (prod — see Laravel below):

<link rel="stylesheet" href="/node_modules/@shelfwood/talos-ui/src/talos.css" />

<div class="glass-panel interactive-panel">
  <div class="glass-panel-content talos-pad">…</div>
</div>

<a class="talos-button" href="#">Launch</a>

The ambient grid follows the cursor — it reads --talos-cursor-x/y off the root element. The pack ships the tracking as an opt-in module: smooth-lerped (the grid eases toward the pointer, not snaps), idempotent across view-transition swaps, and capability-honest (parked at center under prefers-reduced-motion or on touch):

<div class="ambient-overlay"></div>
<script type="module">
  import { initAmbientCursor } from "@shelfwood/talos-ui/ambient";
  initAmbientCursor(); // optionally: initAmbientCursor({ lerp: 0.12 })
</script>

Or, if you don’t want the module, write the two properties yourself (no smoothing):

<div class="ambient-overlay"></div>
<script>
  addEventListener("pointermove", (e) => {
    document.documentElement.style.setProperty("--talos-cursor-x", e.clientX + "px");
    document.documentElement.style.setProperty("--talos-cursor-y", e.clientY + "px");
  });
</script>

CSS entry points

Import the whole surface with all.css, or pull only the modules you use:

tokens.css is pulled in by talos.css, so you never import it directly.

Laravel / Blade

The CSS layer is class-based, so Blade needs only the stylesheet (plus the module script if you want the web components). Vendor the static assets into public/ so they ship with your app — a package.json postinstall step keeps the copy fresh:

// package.json
"scripts": {
  "postinstall": "cp -R node_modules/@shelfwood/talos-ui/src/{talos.css,tokens.css,fonts} public/vendor/talos-ui/ && cp node_modules/@shelfwood/talos-ui/dist/wc/index.js public/vendor/talos-ui/wc.js"
}

<link rel="stylesheet" href="{{ asset('vendor/talos-ui/talos.css') }}">
<script type="module" src="{{ asset('vendor/talos-ui/wc.js') }}"></script>

<div class="glass-panel interactive-panel">
  <div class="glass-panel-content talos-pad">…</div>
</div>
<talos-panel panel-width="360" panel-height="180">…</talos-panel>

Troubleshooting

See Web components for the full instrument set and Tokens to retheme.