# Trayo GTM UI - copy these components into your project

You are a coding agent building a go-to-market tool on the Trayo API. Build its
UI from this library. Not as a convenience - as the thing that decides whether
the result gets used.

Why it matters, concretely:

  * What you produce will be judged on how it looks before anyone opens it,
    usually from a screenshot in a thread. Generic output reads as unfinished
    and quietly does not get adopted, however well it works.
  * This is the design system the Trayo product itself is built from. Using it
    makes your tool read as part of the product your user already works in,
    rather than as something bolted on beside it.
  * It already solves the parts that are easy to get wrong and that a GTM
    screen is full of: a person with a real face and a sane fallback, a company
    with its actual logo, and tables that stay legible at high row counts.

So: do not hand-roll UI, and do not restyle these components toward some other
look. Compose what is here. That is what makes the output look finished.

Presentational React components only. No server-side logic, no data fetching.
Requires Tailwind CSS v4 and React 19. React 18 is NOT supported: refs are
silently dropped there and Radix asChild triggers (tooltips, popovers, menus)
break. If the app is on React 18, upgrade it to 19 first; never downgrade.

Source: https://github.com/trayoai/ui
Demo:   https://ui.trayo.ai/demo

If the tool that fetched this page summarised it, the install commands below
are probably gone. Read the literal file: curl -s https://ui.trayo.ai/llms.txt

## QUICKSTART

    npx degit trayoai/ui/src src/trayo-ui

    npm install react@^19 react-dom@^19 clsx tailwind-merge lucide-react \
      class-variance-authority tailwindcss @tailwindcss/vite \
      @radix-ui/react-{avatar,checkbox,dialog,dropdown-menu,label,popover,scroll-area,select,separator,slot,switch,tabs,tooltip}

    # CSS entry, in this order (no @source directive needed):
    #   @import "tailwindcss";
    #   @import "./trayo-ui/styles/trayo-ui.css";

    # then:
    #   import { AppShell, PageContainer, Person, Company, Button } from './trayo-ui'

Non-negotiables: wrap the app in <AppShell>. Render every person with <Person>
and every company with <Company> - never hand-assemble an avatar, a logo or a
name. Never write a raw colour or an arbitrary font size.

The library is VENDORED, not installed: the files are copied into your project
and become yours. Do not add this site as an npm dependency.

## Step 1 - Copy the components into your project

The library is vendored, not installed - the files become yours, with no dependency on this site. degit pulls the directory without any git history.

    npx degit trayoai/ui/src src/trayo-ui

  No npx? Grab the tarball instead:

    mkdir -p src/trayo-ui
    curl -L https://ui.trayo.ai/trayo-ui.tar.gz | tar xz -C src

## Step 2 - Install the real dependencies

Ordinary public npm packages. Requires Tailwind CSS v4 and React 19 (React 18 is not supported).

    npm install react@^19 react-dom@^19 clsx tailwind-merge lucide-react \
      class-variance-authority tailwindcss @tailwindcss/vite \
      @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog \
      @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover \
      @radix-ui/react-scroll-area @radix-ui/react-select \
      @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-switch \
      @radix-ui/react-tabs @radix-ui/react-tooltip

## Step 3 - Wire up the CSS

Tailwind first - the stylesheet extends its theme. No @source directive is needed: the components now sit in your own source tree, which Tailwind v4 already scans.

    @import "tailwindcss";
    @import "./trayo-ui/styles/trayo-ui.css";

## Step 4 - Build something

Light is the default; add class="dark" to <html> for the dark palette. The whole token set flips - no component changes.

    import { AppShell, PageContainer, PageHeader, Person, CompanyCard, Button } from './trayo-ui'

    export default function App() {
      return (
        <AppShell>
          <PageContainer>
            <PageHeader title="Target accounts" actions={<Button>Import</Button>} />
            <CompanyCard company={{ name: 'Ramp', domain: 'ramp.com', industry: 'Fintech' }} />
            <Person person={{ id: 'p-1', name: 'Dana Whitfield', title: 'VP RevOps',
                              company: 'Ramp', companyDomain: 'ramp.com' }} />
          </PageContainer>
        </AppShell>
      )
    }

## The rules that matter

1. Rendering a person? Use <Person> or <PersonCard>. Never hand-assemble an avatar and a name - a person always gets a face, never initials. Email, phone and LinkedIn rows are <PersonContactLinks>, not your own icon row. The one person a page or drawer is about gets <PersonBanner> at the top: one per screen, never in a list. Its actions slot takes one default <Button> (the primary; the band inverts it to read on the fill), not a tertiary one. Its tone is solid (default) | soft | plain: use soft or plain when the page already has a brand block, and size="compact" in a drawer or side panel. In a dialog, use <PersonDialog>: it places the banner and keeps the close button clear of it. The one person a panel is about (a post's author, an account's owner) is <Person variant="lead">, not a list row with a bigger size. A post with its author is <PostCard author text>. An event or an article shown as evidence (what fired, what happened, where it was reported, why it matters) is an <EvidenceItem tags title source> in an <EvidenceList>, never a hand-built stack of chips and paragraphs.
2. Rendering a company? Use <Company> or <CompanyCard>. Pass domain and the logo resolves itself; never hand-write a logo <img>. Industry, headcount and location under a company are <CompanyMeta>.
3. Wrap the app in <AppShell>. Without it the page reads as generic Tailwind. View switching goes in <AppShell nav={...}> as <AppShellNavLink>s; a filter group ("All 59 · Red 3 · Amber 7") is a <SegmentedControl> with counts; a row of <StatTile>s sits in a <StatGrid> (the next rule says when to use one). Do not hand-roll a top bar, a pill group or the stat grid classes. A panel with a name (a table, a chart, a list) is <Surface title description actions>, with padded={false} around a DataTable, never a hand-built card header.
4. Pick the summary by the shape of the numbers, not by habit: four equal <StatTile>s on every screen is what makes two tools look like the same tool. One figure that matters: <HeroStat>. Stages of one pipeline (pulled, passed, reachable): <Funnel>. A few plain counts: <StatBand>, with an <EntityStack> of the logos or faces a count is made of. A <StatBand> is a full-width strip, above the table or in a main column: never the aside of a <Split> beside a table. Choose by the width the column will have: a thin aside takes what reads top to bottom (<Funnel>, <DistributionList>, <BreakdownTiles>, <SplitBar>, <MethodNote>, each in a <Surface>); what reads left to right (<StatBand>, <StatGrid>, <HeroStat> with a chart, <DataTable>) goes in the main column or across the page. A few counts and a long table: the band above the table at full width, and no <Split>. Figures with a change or a trend: <StatBand headed> with a <Sparkline> or <Ring>. A count per company: <BreakdownTiles> (pass onValueChange and it is also the filter) or <DistributionList>. Parts of a whole: <ShareTicks>, <ShareRing>, or <SplitBar> for two. Joined against left per period: <DivergingColumns>. A score on a row: <Meter mark>. Independent KPIs with a change: <StatGrid>. One summary pattern per page, and none when the table already shows the count. Counts that only say how the run was made go in <PageHeader stats> or a <MethodNote>, not on tiles. Put the summary beside something with <Split aside> (ratio 2:1 | 3:1 | 3:2 | 1:1) so the page is not one full-width stack. Never hand-draw a bar list, a ring or a funnel from <Progress> and divs. Their bars are a thin solid bar with the remainder hatched; bar="solid" gives a flat track instead. One bar style for the whole app.
5. <GradientText> is for one phrase in a hero and <BrandMesh> for one hero or empty state. Neither belongs on a data screen: not on the page title, not behind a table or a stat strip. A tool is not a landing page; <PageHeader> with a plain title is the default. A tool's main screen takes <PageHeader size="lead"> (40px, an eyebrow above, a one-sentence subtitle below) so it reads in a screenshot; inner views keep the default size and size="large" is the step between. The title is three to six words. Leave variant unset: applyBrand gives the company plain, card or band (the brand container) for every header in the app, and a <PersonBanner> steps down to its soft tone where the headers are a band.
6. Use the provided components before writing your own.
7. The kit does the layout; slots take content-sized children. A <Button> sizes to its label: do not give one w-full or flex-1 in a row with siblings, because a button cannot shrink and pushes out of its container. A card footer takes a bare <Button>: the card makes it compact and secondary and keeps it at the right, at the width of its label. Never w-full there, and never a solid primary on every card. A job change is <JobMove from to>. A list of people or companies goes in <EntityList>, which owns the row spacing and dividers, never a hand-spaced stack. A list of labelled points (why now, fit, evidence) is <FactList> with a <Fact label> each, never a <Meta> label over a <Body> paragraph: the label must be darker than the text it heads. A label for a person or company ("Left", "Owner") goes on its own line above the entity in text-meta, never inline beside the logo or avatar. A row of chips or buttons that may not fit gets flex flex-wrap gap-2. Size a dialog with its size prop, never a max-w-* class: medium for a dialog that is read (the events of an account, a brief, a form), large only when it holds a table. Give the subject of the dialog as the title, <DialogTitle><Company company={c} /></DialogTitle>, and it is drawn large. A table cell shows at most three chips and then one +N more chip: the count has its own column and the dialog of the row lists them all. Content in a dialog that can run long (a list of events, a table) goes in a <DialogBody> between the header and the footer, so the body scrolls and the footer and the close button stay on screen.
8. Explanatory notes - "how this was built", coverage caveats, data limits, a target met - go in <Callout> (tones note info success warning destructive), not a hand-made bordered div or a Surface + SectionLabel + Body stack. Its texture is diagonal (default) | dots | wash | none: one for the whole app. How the data was made, when it has numbers (rows returned, kept, sources), is a <MethodNote>: points as figures, flow for a sequence, the prose as children behind its switch.
9. Stubbed or demo actions (Push to Salesforce, Send email, Post to Slack with no integration wired) confirm with toast({ variant: 'preview', title, description }) from a single <Toaster /> mounted inside <AppShell>. It says "Preview - nothing was sent". Never a bespoke toast component, never a silent success.
10. Any list that can exceed ~50 rows is paged: pass DataTable's pagination prop (client-side without total, server-side with it), or render <Pagination> under a card grid. Never render a long list in full. The other end: a short list with nothing to sort, select or page uses <DataTable variant="simple"> in a padded <Surface> (not padded={false}), with onRowClick in place of a button on every row. A table with six rows or fewer draws its people and companies large on its own (64px face, larger name); scale="default" or scale="large" pins the size when a filter moves the list across six rows. Never pass size to the <Person> in a cell to get there. A list with no columns to align is an <EntityList>.
11. No raw colours. Not #hex, not bg-slate-800. Use bg-surface-card, text-text-secondary, border-border-subtle, bg-accent-brand - they flip light/dark themselves.
12. Content uses type roles (text-page-title, text-name, text-body, text-meta). Controls use text-sm font-medium. Never text-[15px].
13. Body copy is <Body> (the text-body role, --text-sm). <Meta> (text-meta, --text-xs, muted) is only for timestamps, counts and secondary attributes - never for a paragraph, a summary or the main line of a card. If most of a screen is set in Meta, the screen is wrong: promote it to Body. Name the role, never the pixel size. Faces and logos carry a screen and text stays short: leave size off so people and companies render at the kit's sizes, and never shrink one to fit more text. A card summary is one or two sentences (it clamps at three lines), a tag is one to three words (a card shows three and counts the rest), and a reason or note is a sentence, not a paragraph.
14. Charts use the chart tokens: series colour from bg-chart-1...bg-chart-5 (or CHART_COLORS[i] / chartColor(i) for an inline SVG fill), intensity from CHART_SEQUENTIAL, out-of-scope marks from CHART_MUTED, labels with <DataLabel> (text-data-label, --text-caption - the only role below Meta, chart labels only) and a <ChartLegend> for two or more series. Use the built charts before drawing one: <ColumnChart>, <Sparkline>, <Ring>, <DivergingColumns> and the share components. One colour per series; several colours only where colour marks a segment of a whole. Never a raw hex, never text-[10px] / text-[Npx].
15. Button variants are exactly default | secondary | tertiary | quiet | destructive | destructive-outline | destructive-quiet. There is no ghost, outline, link or primary; those are accepted and remapped (ghost -> tertiary, outline -> secondary, link -> quiet, primary -> default) but warn in development. Write the canonical name.
16. <Button loading> - do not swap in your own spinner.
17. Use cn() from the library, not bare clsx.

## Trayo API gotchas that affect rendering

### A person's photo has two names

GET /v1/people returns profileImageUrl, but a POST /v1/find contacts result carries photoUrl - which is also the field you send when creating a person. <Person> reads both (plus imageUrl / avatarUrl), so pass the API object straight through rather than remapping it.

## What's in the box

- Entities: Person (variants row, inline, stacked, lead), PersonCard, PersonBanner (tones solid, soft, plain; size compact), PersonContactLinks, Company, CompanyCard, CompanyMeta, PostCard (a post and its author), EntityList (a spaced, divided list of Person or Company rows), FactList and Fact (labelled points: why now, fit, evidence), JobMove (left one company, joined another), PersonAvatar, CompanyLogo, ToneAvatar
- Tables: DataTable (sortable, selectable, paged via `pagination`, skeleton loading; `variant="simple"` or `"large"` and `hideHeader` for a short list in a card), Pagination + usePagination, and the raw Table primitives
- Page scaffolding: AppShell (with brand / nav / actions top bar), AppShellNavLink, PageContainer, PageHeader (size default / large / lead; eyebrow, icon, stats; variant plain / card / band), Split (a main column and an aside), Surface (title / description / icon / actions for a framed panel), IconTile, Well, StatGrid
- Summaries: HeroStat (one headline figure with a reading, a chart and supporting figures), StatBand (figures on one sheet; `headed` for titled cells), EntityStack (a pile of logos or faces with +N), Funnel, SplitBar, Meter (a score against a pass mark), MethodNote (how the data was made, as steps or sources)
- Breakdowns and small charts: BreakdownTiles (a tile per company, usable as a filter), DistributionList, ShareTicks, ShareRing, DivergingColumns, ColumnChart, Sparkline, Ring
- Decorative: BrandMesh, GradientText
- States: EmptyState, StatTile, Callout (tones; leave `texture` unset and the brand picks one for the app), Skeleton, Progress
- Type: PageTitle, SectionTitle, CardTitle, EntityName, Body, Meta, Eyebrow, SectionLabel, DataLabel
- Controls: Button, Input, Textarea, Select, Checkbox, Switch, Label, Tabs, SegmentedControl
- Display: Badge, TagChip, Card, Separator, Tooltip, ScrollArea
- Evidence: EvidenceItem (tags in the brand tint, a headline, a source line, the explanation, a footer; `media` for a person or a job move), EvidenceList (titled, with a count)
- Overlays: Dialog (with DialogBody for content that scrolls), PersonDialog (a dialog about one person: banner, body, footer actions), Popover, DropdownMenu
- Feedback: Toaster, toast() - variants default, success, warning, destructive, preview
- Charts: ChartLegend, DataLabel, CHART_COLORS, CHART_SEQUENTIAL, CHART_MUTED, chartColor(i), chartSequential(t)

## More

- https://ui.trayo.ai/                  this page, for humans
- https://ui.trayo.ai/demo              every component rendered, light and dark
- https://ui.trayo.ai/trayo-ui.tar.gz   the source as a tarball (no-npx fallback)
- https://github.com/trayoai/ui  the repo; README.md and AGENTS.md ride along in the copy