# TipSharks Design Tokens
Shared visual primitives for the TipSharks platform — colors, spacing, border radii, and typography.
## Source of Truth
| File | Format | Consumed By |
|------|--------|-------------|
| [`design-tokens.json`](../../design-tokens.json) | JSON | Backend services, code generation, validation |
| [`design-tokens.schema.json`](../../design-tokens.schema.json) | JSON Schema | Validating `design-tokens.json` |
| [`design-tokens.css`](../../design-tokens.css) | CSS custom properties | Web UIs (tab-api-ingest, tipsharks-elo-api) |
| [`design-tokens.js`](../../design-tokens.js) | ES module | React Native app (tipsharks-client) |
**Always edit `design-tokens.json` first**, then regenerate the other formats to keep them in sync.
## Color Palette
| Token | Value | Usage |
|-------|-------|-------|
| `brand.navy` | `#0f172a` | Primary dark — navbars, headers, dark mode background |
| `brand.cyan` | `#06b6d4` | Primary accent — CTAs, links, highlights |
| `brand.navyLight` | `#1e293b` | Dark card backgrounds, surfaces |
| `semantic.success` | `#22c55e` | Positive ratings, profit indicators |
| `semantic.warning` | `#eab308` | Marginals, mid-confidence tips |
| `semantic.danger` | `#dc2626` | Negative ratings, loss indicators |
| `semantic.info` | `#3b82f6` | Informational badges, tooltips |
## How to Use
### Web UI (Bootstrap / Tailwind)
```html
TipSharks
```
#### Bootstrap 5 overrides example
```css
/* In your custom stylesheet loaded after Bootstrap */
:root {
--bs-primary: var(--ts-color-brand-navy);
--bs-info: var(--ts-color-brand-cyan);
--bs-success: var(--ts-color-semantic-success);
--bs-warning: var(--ts-color-semantic-warning);
--bs-danger: var(--ts-color-semantic-danger);
}
```
### React Native (tipsharks-client)
```js
import { colors, spacing, borderRadius, typography } from '../../design-tokens';
// Use in StyleSheet
const styles = StyleSheet.create({
container: {
backgroundColor: colors.background.light,
padding: spacing.md,
borderRadius: borderRadius.md,
},
title: {
color: colors.text.primary,
fontSize: typography.fontSize.lg,
fontFamily: typography.fontFamily.sans,
},
accent: {
color: colors.brand.cyan,
},
});
// Dark mode support
const isDark = useColorScheme() === 'dark';
const themeColors = isDark ? theme.dark : theme.light;
Hello
```
### Backend / API (Python / Jinja templates)
```python
import json
with open("design-tokens.json") as f:
tokens = json.load(f)
brand_navy = tokens["tokens"]["color"]["brand"]["navy"]["value"]
```
For server-rendered HTML (Jinja templates), pass the CSS file path or embed tokens as inline styles.
### Validating the JSON
```bash
# Using Python
python -c "
import json, jsonschema
with open('design-tokens.schema.json') as s, open('design-tokens.json') as d:
jsonschema.validate(json.load(d), json.load(s))
print('Tokens are valid')
"
# Using ajv (Node.js)
npx ajv validate -s design-tokens.schema.json -d design-tokens.json
```
## Adding New Tokens
1. Add the token to `design-tokens.json` under the appropriate category
2. Update `design-tokens.css` with the corresponding `--ts-*` custom property
3. Update `design-tokens.js` with the new export
4. Update the schema if adding a new top-level category
## Versioning
Design tokens follow [semver](https://semver.org/):
- **MAJOR**: Breaking rename/removal of tokens
- **MINOR**: New tokens added
- **PATCH**: Value corrections (e.g. color tweaks)