# Integration

Clone the repository, select an identity, and copy the files you need to your own project's static asset directory. Keep relevant licenses. Pin a release tag or commit when using a submodule or automated copy. Do not hotlink authenticated Gitea raw-file URLs; access may require sign-in and MIME behavior varies.

## Minimal CSS integration

```html
<link rel="stylesheet" href="/brand/assets/fonts/fonts.css">
<link rel="stylesheet" href="/brand/tokens/tokens.css">
<section class="wsa-brand" data-identity="blue" data-appearance="dark">
  <h2>Your product</h2>
</section>
```

```css
.product-panel {
  font-family: var(--wsa-font);
  color: var(--wsa-foreground);
  background: var(--wsa-background);
  padding: var(--wsa-space-24);
}
```

Add `product-panel` to the example section to apply those styles. Identity is `original`, `red` or `blue`. Appearance is `light`, `dark` or `auto`; omit appearance for automatic system selection. The prefixed tokens inherit to descendants but apply no global reset. A nested branded component should declare its own identity/appearance to avoid inheriting a different component's tokens.

## Attribution

The [footer example](../examples/footer.html) shows compact and roomy footers for all identities and appearances. Copy the desired `<a>` and include `examples/footer.css` plus `tokens/tokens.css`; optionally include fonts. Update relative asset paths for your application's directory structure. Keep the single link pointing to `https://ws.agency/`.

The component has a meaningful link label, decorative images with empty alt text, keyboard focus and a minimum 44 px target height. It has no JavaScript dependency. The two monochrome/color images switch with explicit `data-appearance` or the system preference. A host site's custom theme must set this attribute too; a parent class called `dark` is not automatically observed.

For attribution without visible text, use the **Heart + mark** example or `assets/badges/<identity>/made-with-love-symbols-<light|dark>.svg` (PNG is also included). Keep the link's `aria-label="Made with love by WS Agency"` even though only the two icons are visible. The outlined heart and sign share a 20 px visible height and a common vertical center; the HTML group stays together when surrounding text wraps. The heart is a new kit illustration, preserved in `sources/kit/heart.svg`.

For a README, use [the Markdown examples](../examples/README-badges.md). Copy badge files into that repository first. Plain SVG badges have outlined text and an opaque background, so they render without installed fonts and remain legible on another site's background.

## Favicons and app icons

```html
<link rel="icon" type="image/svg+xml" href="/brand/assets/icons/original/favicon.svg?v=1">
<link rel="apple-touch-icon" sizes="180x180" href="/brand/assets/icons/original/icon-light-180.png">
```

Use your selected identity directory. Adaptive SVG favicons follow browser/system appearance, independently of a site's own theme switch. Fixed `favicon-light.svg` / `favicon-dark.svg` variants and 16, 32, 48, 180, 192 and 512 px PNGs are available. Large app icons use an opaque background; small favicon PNGs remain transparent. Choose explicit light/dark icons for environments without adaptive SVG support.

These files are generic branding assets; application-store masks, safe areas and platform packaging must be checked by each app. The Original adaptive SVG preserves the favicon already approved for the marketing site.

## React, Vue and other frameworks

Use the HTML snippet as ordinary markup and adapt attributes (`className` in JSX) as needed. The CSS and image assets are framework-independent. The repository does not require a component runtime or package installation in consumer projects.

## Update and rebuild

1. Update source files only from an authenticated source and record their URL and checksum. Review source imports separately: the ordinary build refuses changes to the original-artwork hashes already saved in `sources/manifest.json`.
2. Edit `tokens/tokens.json` or `scripts/build.py` for derived artwork; never overwrite an original with an export.
3. Rebuild and validate as described in the README.
4. Inspect affected renders and integration examples, update the changelog, then tag a new release. Consumers opt in to updates.
