---
name: framebrick
description: Build React and Next.js interfaces with Framebrick UI, a shadcn registry of animated components (text effects, accordions, slideshows, marquees, scroll reveals). Use when a task asks for a motion effect or an animated section, or when the project's components.json lists @framebrick.
---

# Building with Framebrick UI

Framebrick UI is a free registry of animated React components for shadcn/ui projects. The components copy into the
project (you own the files), use Motion, and follow the project's shadcn theme. Docs: https://framebrick.co/components

## Before you start

- The project is Next.js or React with Tailwind CSS 4 and shadcn/ui initialised (a `components.json` exists). If it is
  not, run `npx shadcn@latest init` first.
- `components.json` lists the registry. Add it if it is missing:

  ```json
  { "registries": { "@framebrick": "https://framebrick.co/r/{name}.json" } }
  ```

- Prefer the Framebrick MCP server when it is connected (`https://mcp.framebrick.co`: `search`, `get_component`, `get_block`, `install_command`, `plan_page`); otherwise the shadcn MCP server when it is connected (`npx shadcn@latest mcp init --client <client>` sets it up). The
  CLI does the same work without it.

## Workflow

1. **Search first.** MCP: `search_items_in_registries` with `registries: ["@framebrick"]`. CLI:
   `npx shadcn@latest search @framebrick -q <word>`. If nothing fits, say so. Do not hand-write an effect the registry
   already has (accordion list, marquee, text appear, slideshow, scroll reveal, zoom card, step sequence...).
2. **Read before you use.** MCP: `view_items_in_registries`. CLI: `npx shadcn@latest view @framebrick/<name>`. The page
   `https://framebrick.co/components/<name>` has the props table, usage and notes. Never invent a prop.
3. **Install.** `npx shadcn@latest add @framebrick/<name>`. The file lands in the project's `ui` folder
   (`components/ui` by default), with its packages (usually only `motion`).
4. **Wire it in.** Keep the component's structure and motion. Replace the demo content with the project's own and
   pass real data through the documented props.
5. **Check.** Reduced motion, keyboard, a 390 px wide screen, and dark mode if the project has it.

## Rules

- Motion: wrap the app once in `<MotionConfig reducedMotion="user">` (from `motion/react`, in a client providers
  component). That setting only skips movement and size changes. Components that animate other things (opacity, blur,
  CSS variables) handle reduced motion themselves, so leave that code in.
- Server and client: a component that takes a function prop (a render prop or a callback) must be rendered from a
  client component (`"use client"`), or the server page fails to prerender.
- Look: the components read the shadcn tokens (`bg-background`, `text-foreground`, `border-border`...). Do not
  hard-code colours or fonts; the project's theme decides.
- Text effects take the whole sentence as the `text` prop, so screen readers read it once.
- The preview on the website is wrapped in a frame. Copy from the installed file, not from the page.

## What is not available

- Framebrick page blocks come with a Pro or Ultimate plan. The `/r/blocks` registry answers 401 without the member's token
  (`@framebrick-blocks` in `components.json` with an `Authorization: Bearer ${FRAMEBRICK_TOKEN}` header, token from
  https://framebrick.co/account). If the project has no such registry entry or the token is missing, do not try to install
  blocks; tell the user what is needed.
- Page blocks and whole templates have their own skills: `framebrick-blocks` and `framebrick-templates` (install all three with `curl -fsSL https://framebrick.co/install | node -`).
- Whole templates (Framer, HTML, Astro, Next.js) are on https://framebrick.co/templates, with guides at
  https://framebrick.co/docs.