# WS Agency Design System

A portable brand kit for websites, social media, custom applications and open-source attribution. **Original, Red and Blue are equal-status identities.** Choose the one that fits your project and use it consistently.

![Three equal-status WS Agency identities](docs/previews/identities.png)

**Start here:** open [`index.html`](index.html) in your browser for the visual gallery, or serve this directory locally with `python3 -m http.server 4173 --bind 127.0.0.1` and visit `http://localhost:4173`. No install, build or network connection is needed to use the shipped files. Gitea may show HTML source rather than run it: clone/download the repository first.

```sh
git clone git@git.wsagency.io:ws-agency/wsagency-design.git
cd wsagency-design
git checkout v1.2.0
```

## Pick what you need

| Need | Go to |
| --- | --- |
| Logo, sign or wordmark | [Curated logos](assets/logos/) · [selection guide](docs/brand-guide.md) |
| Original source artwork | [193-file archive index](sources/index.html), including AI/PDF/PNG/SVG |
| Desktop / self-hosted fonts | [Fonts](assets/fonts/) · [typography guide](docs/typography.md) |
| CSS variables / JSON tokens | [Tokens](tokens/) |
| Made with love / Built by / Open-source credit | [Badge assets](assets/badges/) · [Markdown examples](examples/README-badges.md) |
| App or website footer | [Live HTML examples](examples/footer.html) · [component CSS](examples/footer.css) |
| Mobile apps (Talkyto / CHRIS) | [Placement examples](examples/mobile.html) · [developer guide](docs/mobile-apps.md) |
| Company details and Croatian website disclosures | [Company example](examples/company.html) · [shared data](data/company.json) · [official-source legal guide](docs/croatian-web-disclosures.md) |
| Social posts, stories, previews and avatars | [Social templates](assets/social/) |
| Favicons and app icons | [Icons](assets/icons/) |
| Integration instructions | [Integration guide](docs/integration.md) |
| Licenses and permitted use | [Usage and licenses](docs/usage-and-licenses.md) |

## Quick attribution

Copy the selected badge into your project's `brand/` directory and add:

```markdown
[![Made with love by WS Agency](brand/made-with-love-light.svg)](https://ws.agency/)
```

Use attribution only where it is accurate. Badges use real logo geometry and outlined lettering; no external badge service or installed font is required. Do not hotlink private Gitea files from public projects.

Prefer just the heart and sign? Copy `made-with-love-symbols-light.svg` (or its dark/PNG variant) and keep the same descriptive alt text. Both icons have matching outline weight, a 20 px visible height and a shared vertical center. The footer examples also include this option.

For “Made with ♥ by” followed only by the agency sign, use `made-with-love-mark-light.svg` (or dark/PNG). This keeps the wording and removes the visible agency name. HTML equivalents are included in the footer examples.

## What is included

- 193 unchanged original files from the supplied Drive brand folder, with byte sizes, source URLs and SHA-256 hashes.
- Full logos, wordmarks and signs for each identity, with color/dark/white SVGs and transparent PNGs.
- Manrope, Inter, IBM Plex Mono and JetBrains Mono; desktop TTF, full-glyph WOFF2 and original OFL licenses.
- Opt-in, prefixed light/dark tokens without a global CSS reset.
- Five credit compositions, in three identities and two appearances, as SVG and PNG.
- Five social canvas formats per identity and appearance: editable SVG, outlined SVG and PNG sample.
- Adaptive/fixed favicons, PNG icons, compact and roomy footer examples.

The source web palette snapshot is recorded in `tokens/tokens.json`. Spacing/type scales, Original UI surfaces, attribution compositions and social layouts are new kit recommendations; they are not presented as historical rules. No changes are made to the production marketing website by using this repository.

## Reproduce exports

Using Python 3.12+ and the native Cairo library (for example `brew install cairo` on macOS or your Linux distribution's Cairo package):

```sh
python3 -m venv .venv
.venv/bin/pip install -r scripts/requirements.txt
.venv/bin/python scripts/build.py
.venv/bin/python scripts/gallery.py
.venv/bin/python scripts/validate.py
.venv/bin/python scripts/test_source_integrity.py
```

On Apple Silicon macOS, if Cairo cannot be found, prefix the build and source-integrity test commands with `DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`. Dependencies are required only to regenerate/validate assets, not to consume them. Builds use bundled inputs and need no Drive or font downloads. WOFF2 and font metadata are regenerated from the desktop TTFs, with full character maps checked against the originals. The build checks the existing original-artwork hashes before writing exports; changing that baseline requires a separate, deliberate source-import review.

Generated PNGs and outlined SVGs are committed. Edit source tokens/generators or editable social SVGs as appropriate; do not edit historical originals. Customized social files should live in your project so a kit rebuild does not overwrite them. See [verification](docs/verification.md) and [changelog](CHANGELOG.md).

## Versioning

Pin the release tag or commit in downstream projects. Breaking filenames or token names require a major version; new assets can be minor versions; corrections are patches. Updates are opt-in. Keep source provenance and font notices when copying files. Code is MIT-licensed separately from artwork and fonts; see `LICENSE-CODE`.

## Publishing the gallery

Serve the repository as static files at `design.ws.agency`, with `index.html` as the entry point. Review the bundled source archive before making the entire directory public. The Gitea repository link uses its existing employee access controls; the static gallery does not implement authentication. The company-details page is explicitly an incomplete example until the pending accounting fields are confirmed.