Using icons

#Triggers

• hover plays the choreography while the trigger is hovered or keyboard-focused, and settles back when it's released. The trigger is the closest ancestor with data-yj-trigger, otherwise the closest button, link, summary, label or element with a button, link, menu item, tab, switch or option role, otherwise the icon itself. Only keyboard focus counts, so a button that keeps focus after a click still settles when the pointer leaves.
• mount plays once, as the icon appears.
• loop repeats while the icon is on screen and the tab is visible, and pauses otherwise. Most icons cycle: they play for two deliberate steps and rest for one. Loaders (LoaderRingIcon, LoaderDotsIcon and HourglassIcon) run continuously instead, and they loop by default.
• none holds the resting pose.

A controlled active wins over every trigger. true holds the icon in its active pose, false at rest.

#State icons

State icons carry two states, such as menu and close, play and pause, muted and live, or saved and unsaved. Drive them from your own state with active. The icon shows the state, and the button around it carries the meaning for assistive technology. useIconState wires up both.

Reversing plays the opposite choreography, and a toggle mid-morph turns back from wherever the icon is. Morphs has all of them.

#Size and stroke

size sets the width and height. It takes a number of pixels or any CSS length, so size="100%" fills its box. strokeWidth is in view-box units, so it scales with the icon: the default 1.5 draws 1px lines at 16px and 2px lines at 32px.

Inside Youj's UI controls, leave size alone: a Button, a menu item or a tab sizes its icons to the control. Pass only the stroke.

#Brand marks

Brand marks sit in their own brand category, for signing in with a service or linking to it: BrandGithubIcon, BrandXIcon, BrandLinkedinIcon, BrandDiscordIcon and BrandFigmaIcon. Each is drawn from its owner's official asset, in one color, and never animates: the guidelines don't allow a mark to be altered, and a moving mark is an altered one.

import { Button } from '@youj/react'
import { BrandGithubIcon } from '@youj/icons'

<Button variant="outline">
  <BrandGithubIcon />
  Continue with GitHub
</Button>

• Use a mark only to refer to its service: a sign-in button, a link to a profile or project, a row of social links. Never as your own logo, and never so it suggests the service endorses you.
• Keep it as drawn, in black or white (the foreground color). GitHub also allows gray or green, LinkedIn its blue, Discord its Blurple. Don't recolor it in your accent, stretch it or combine it with other marks or words.
• Name the service beside the mark where you can; Discord asks for it.
• Google, Apple, Microsoft, Slack and GitLab aren't in the set. Their guidelines require their own artwork (Google's full-color G, Apple's and Microsoft's sign-in buttons) or don't allow their logos to be redistributed, so use the sign-in button artwork each one provides.

#Continue with Google

Google is the one exception to the single-color rule, so it isn't an icon here. The auth blocks draw Google's button from its Sign in with Google guidelines, in blocks/auth/shell/google-mark.tsx:

• The standard four-color G, never monochrome, recolored or resized out of proportion.
• Google's own button colors, not your theme's: the light theme (white fill, #747775 stroke, #1F1F1F text) in a light scope and the dark theme (#131314, #8E918F, #E3E3E3) in a dark one, following each scope's color-scheme. googleButton.neutral is the neutral theme (#F2F2F2, no stroke).
• An approved label: "Continue with Google", "Sign in with Google" or "Sign up with Google", translated where the page is.
• The same size and weight as the other sign-in buttons beside it.

Those colors are the one raw-color exception to Youj's token lint, allowlisted for that file alone. Google specifies Google Sans Medium for the label; the block uses your UI font, so load Google Sans if you need strict compliance.

The marks are their owners' trademarks, used under each owner's brand guidelines, and aren't covered by Youj's MIT license. Credits links every guideline.

#How an icon is built

Each icon is a createIcon definition. variants(k) receives the Youj timing object, so every duration and spring comes from the tokens, and the Speed control and reduced motion reach every part. Each part defines a rest and an active pose, and optionally a from pose for trigger="mount". render draws the parts as Motion elements. This is the complete source of CheckIcon:

import { motion } from 'motion/react'
import { createIcon, drawIn, drawn, hidden, origin } from '@youj/icons'

/** Draws its stroke with a decisive ease-out, then settles with a tiny spring. */
export const CheckIcon = createIcon({
  name: 'check',
  category: 'actions',
  keywords: ['done', 'complete', 'confirm', 'ok', 'success', 'tick'],
  variants: (k) => ({
    mark: {
      from: { ...hidden, scale: 0.9 },
      rest: { ...drawn(k), scale: 1 },
      active: {
        ...drawIn(k, 'slow'),
        scale: [0.88, 1],
        transition: { ...drawIn(k, 'slow').transition, scale: { ...k.spring('settle'), delay: k.duration('base') } },
      },
    },
  }),
  render: (v) => <motion.path d="M4 12.5 L9 17.5 L20 6.5" variants={v.mark} style={origin(12, 12)} />,
})

The engine does the rest: it resolves the trigger, pauses loops offscreen, sets the ARIA attributes, and under reduced motion turns every variant into its final pose with no transition. A state icon adds states: ['menu', 'close'], and its active pose is the second state.

The choreography helpers come from the same entry:

Every component carries meta with its name, category, keywords, states and defaultTrigger. The icons array holds the whole set in alphabetical order, and ICON_CATEGORIES lists the categories the explorer groups them by.