feat(frontend): Create Global Arbellar-Frontend Style Guide


## Description

Create a centralized `STYLE-GUIDE.md` that documents the global visual styling system used across the **Arbellar-Frontend** application.

The style guide should serve as the single contributor reference for Arbellar's global theme, colors, typography, visual effects, dark/light mode behavior, Tailwind theme tokens, and styling conventions.

Arbellar is a user-funded, non-custodial atomic arbitrage platform built on Stellar. Its interface should communicate **trust, security, transparency, automation, and futuristic DeFi infrastructure** through a professional dark-first visual system.

The style guide must remain consistent with the existing Arbellar-Frontend project architecture and should document where global styling, theme initialization, theme state, reusable UI components, and Tailwind configuration are implemented.

---

## Scope

Create:

```text
STYLE-GUIDE.md
```

at the project root.

The document should cover:

* Global light/dark theme behavior
* Theme initialization and persistence
* Global CSS and Tailwind configuration
* Arbellar color tokens
* Typography and text hierarchy
* Backgrounds and surfaces
* Borders and radius conventions
* Glow and shadow effects
* Buttons and interactive states
* Cards and panels
* Responsive styling conventions
* Accessibility requirements
* Animation and reduced-motion behavior
* Contributor styling rules
* Relevant project files and directories

The style guide should document the existing project structure rather than introduce a new architecture.

---

## Light/Dark Mode

### Source of Truth

Theme state should be applied to the root `<html>` element using:

* `class="dark"` for Tailwind's `dark:` variant
* `data-theme="dark" | "light"` as an auxiliary theme indicator

Theme persistence should use an Arbellar-specific localStorage key:

```text
localStorage["arbellar-theme"]
```

Supported values:

```text
"dark"
"light"
```

Do not use StellarProof-specific theme keys or references.

### Default Theme

The default experience should be **dark mode**.

If:

```text
localStorage["arbellar-theme"] === "light"
```

the application should load in light mode.

If no theme preference exists, the application should default to dark mode.

---

## Files & Directories

The style guide should document the project's existing styling responsibilities using the following structure where applicable.

### Theme Initialization

```text
app/layout.tsx
```

Responsible for:

* Setting the default theme on `<html>` for the initial render
* Preventing an unnecessary flash between themes
* Synchronizing the root HTML theme attributes with localStorage

### Global Theme State

```text
app/context/ThemeContext.tsx
```

Responsible for exposing:

```ts
{
  theme,
  toggleTheme
}
```

The context should:

* Read the persisted Arbellar theme preference
* Write theme changes to `localStorage["arbellar-theme"]`
* Toggle the `.dark` class
* Update the `data-theme` attribute

### Theme Toggle

```text
components/ThemeToggle.tsx
```

Responsible for:

* Calling `toggleTheme()`
* Providing a clear visual theme toggle
* Using appropriate sun/moon icons
* Remaining keyboard accessible

### Global CSS

```text
app/globals.css
```

Responsible for:

* Tailwind CSS entrypoint
* Global CSS variables
* Arbellar theme tokens
* Light and dark theme overrides
* Global base styles
* Tailwind v4 dark-mode configuration

The following Tailwind v4 custom variant must not be removed if the project uses this approach:

```css
@custom-variant dark (&:where(.dark, .dark *));
```

Removing the custom dark variant can break existing `dark:` utility styling.

### Tailwind Configuration

Document the relevant Tailwind configuration file used by the project, such as:

```text
tailwind.config.ts
```

or:

```text
tailwind.config.js
```

The configuration should remain aligned with the tokens documented in `STYLE-GUIDE.md`.

---

# Arbellar Visual Direction

Arbellar's visual identity should combine:

* Dark futuristic DeFi aesthetics
* Stellar ecosystem influence
* Professional financial interfaces
* Subtle neon illumination
* High contrast
* Clean information hierarchy
* Secure and trustworthy presentation
* Teal-based technology accents
* Stellar yellow highlights

The interface should feel **advanced and automated without becoming visually noisy**.

Avoid excessive gradients, excessive glow, overly bright surfaces, or decorative effects that reduce readability.

---

# Global Theme Tokens

These tokens should be defined centrally through the project's global CSS/Tailwind theme system.

## Primary Colors

### Medium-Dark Teal

```text
primary: #0D9488
```

Used for:

* Primary buttons
* Navigation elements
* Interactive controls
* Cards and panels
* Borders
* Main Arbellar brand elements

### Light Glow Teal

```text
accent: #2FF3E0
```

Used for:

* Neon highlights
* Hover states
* Active states
* Glowing borders
* Icons
* Futuristic accents
* Important interactive indicators

### Stellar Yellow

```text
stellar-yellow: #FDDA24
```

Used selectively for:

* Stellar ecosystem references
* Important highlights
* Status indicators
* Accent graphics
* Brand-adjacent visual elements

The yellow should complement the Arbellar teal rather than replace the primary teal identity.

---

## Supporting Colors

### Dark Background

```text
background: #0B1020
```

### Alternative Dark Surface

```text
surface: #111827
```

### Primary Foreground

```text
foreground: #F6F7F8
```

### Muted Foreground

Use a subdued neutral tone for:

* Secondary descriptions
* Supporting information
* Metadata
* Less important labels

### Dark Teal

```text
primary-dark: #0F766E
```

### Light Teal

```text
primary-light: #14B8A6
```

### Yellow Hover

```text
stellar-yellow-light: #FFE45C
```

### Dark Yellow

```text
stellar-yellow-dark: #D9B800
```

---

# Color Usage Rules

Use:

```text
#0D9488
```

as the primary Arbellar brand color.

Use:

```text
#2FF3E0
```

for futuristic highlights and controlled glow effects.

Use:

```text
#FDDA24
```

sparingly as a Stellar ecosystem accent.

Use dark navy/near-black surfaces such as:

```text
#0B1020
#111827
```

as the primary application environment.

Do not use bright colors for large surfaces unless there is a clear accessibility or semantic reason.

Avoid using glow effects on every element. Glow should establish hierarchy and emphasize important interactive or system states.

---

# Glow Effects

The light teal may use a controlled neon glow:

```css
box-shadow:
  0 0 10px #2FF3E0,
  0 0 25px rgba(47, 243, 224, 0.6),
  0 0 50px rgba(47, 243, 224, 0.3);
```

Recommended reusable shadow tokens include:

```text
shadow-glow
shadow-header
shadow-button-glow
shadow-button-glow-secondary
```

Glow effects should be subtle enough to preserve readability and performance.

---

# Typography

Typography should prioritize:

1. Readability
2. Strong information hierarchy
3. Professional financial-product presentation
4. Clear numeric data
5. Responsive scaling

Recommended hierarchy:

* Large display typography for landing-page headlines
* Strong headings for sections
* Medium-weight subheadings
* Highly readable body text
* Smaller muted text for metadata and supporting information

Avoid excessive font weights and decorative typography that makes financial or transaction information difficult to scan.

---

# Backgrounds & Surfaces

The primary application environment should use dark backgrounds.

Recommended hierarchy:

```text
Page background
↓
Section background
↓
Card / panel surface
↓
Interactive element
↓
Highlighted state
```

Surfaces should have enough contrast to distinguish cards, panels, navigation, and content areas without relying exclusively on shadows or glow.

Subtle atmospheric effects may be used, including:

* Soft gradients
* Fine dotted textures
* Low-opacity grid patterns
* Subtle noise
* Teal radial glows
* Stellar-inspired visual accents

These effects must remain secondary to the interface content.

---

# Buttons & Interactive Elements

Primary actions should use the Arbellar teal:

```text
#0D9488
```

Hover and active states may transition toward:

```text
#2FF3E0
```

Buttons should provide clear visual feedback for:

* Default
* Hover
* Focus
* Active
* Disabled
* Loading

Interactive controls must maintain sufficient contrast and visible keyboard focus indicators.

Do not use animation or glow as the only indication of interaction state.

---

# Cards & Panels

Cards should use dark surfaces with subtle borders.

Recommended visual characteristics:

* Dark surface
* Low-contrast border
* Moderate corner radius
* Subtle shadow
* Optional teal highlight on hover
* Clear internal spacing

Cards displaying financial or arbitrage information should prioritize information clarity over decorative styling.

---

# Status & Financial Indicators

The interface should clearly distinguish states such as:

* Successful
* Pending
* Failed
* Warning
* Informational
* Active
* Inactive

Color should not be the only method of communicating status.

This is particularly important for:

* Transaction states
* Arbitrage opportunities
* Vault operations
* P&L information
* Risk warnings
* Slippage warnings

Avoid styling profitable outcomes in a way that implies guaranteed returns.

---

# Responsive Design

Arbellar-Frontend follows a mobile-first approach.

Styles should be tested across:

* Mobile
* Tablet
* Desktop
* Large desktop displays

Components should avoid:

* Horizontal overflow
* Fixed-width layouts that break on small screens
* Text clipping
* Unusable touch targets
* Layout shifts caused by dynamic content

Financial and transaction interfaces should remain usable on smaller screens.

---

# Accessibility

The style system must support WCAG 2.1 AA principles.

Contributors should ensure:

* Sufficient color contrast
* Keyboard navigation
* Visible focus states
* Semantic HTML
* Accessible form controls
* Accessible buttons
* Meaningful labels
* Reduced-motion support
* No information conveyed by color alone

Teal glow and Stellar yellow should never be relied upon as the only method of communicating meaning.

---

# Animation & Motion

Animations should reinforce the futuristic and automated nature of Arbellar without distracting from core financial information.

Appropriate uses include:

* Hover transitions
* Button interactions
* Card elevation
* Section entrance animations
* Subtle background motion
* Loading indicators
* Arbitrage activity indicators

Animations should remain short and purposeful.

Respect:

```css
prefers-reduced-motion: reduce
```

When reduced motion is enabled, unnecessary transitions and decorative animations should be minimized or disabled.

---

# Contributor Rules

### 1. Use centralized theme tokens

Prefer project-defined theme tokens instead of repeatedly introducing arbitrary colors.

Example:

```tsx
<div className="bg-primary text-white">
  ...
</div>
```

### 2. Use `dark:` for theme-specific styling

When a component needs different styling between themes:

```tsx
<div className="bg-white text-gray-900 dark:bg-[#0B1020] dark:text-white">
  ...
</div>
```

Prefer semantic theme tokens when available instead of hardcoding values throughout components.

### 3. Access theme through the theme context

Client components that need theme state should use the project's theme context:

```tsx
"use client";

import { useTheme } from "@/app/context/ThemeContext";

export function ExampleThemeButton() {
  const { theme, toggleTheme } = useTheme();

  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  );
}
```

### 4. Avoid arbitrary visual styles

Do not introduce new colors, shadows, gradients, or typography systems without considering whether the style belongs in the global design system.

### 5. Preserve visual consistency

New components should follow the established:

* Color tokens
* Spacing system
* Typography hierarchy
* Border radius
* Shadows
* Interactive states
* Responsive behavior
* Accessibility standards

---

# Security & Trust Visual Principles

Because Arbellar handles user-funded DeFi interactions, visual design must reinforce trust.

The UI should clearly communicate:

* Non-custodial architecture
* User control of funds
* Transaction previews
* Risk warnings
* Slippage limits
* Arbitrage execution status
* Transparent fees
* Transaction outcomes

The design must never visually imply guaranteed profits or risk-free returns.

Marketing and dashboard components should distinguish between:

* Potential opportunities
* Estimated outcomes
* Executed transactions
* Historical performance

---

# Acceptance Criteria

* [ ] `STYLE-GUIDE.md` is created at the project root.
* [ ] No StellarProof-specific terminology, colors, paths, localStorage keys, or descriptions remain.
* [ ] The guide is fully adapted to Arbellar-Frontend.
* [ ] Global light/dark mode behavior is documented.
* [ ] `arbellar-theme` is used as the documented persistence key.
* [ ] Dark mode is documented as the default theme.
* [ ] Arbellar teal colors are documented.
* [ ] Stellar yellow `#FDDA24` is documented as a supporting ecosystem accent.
* [ ] Dark background colors are documented.
* [ ] Glow and shadow usage is documented.
* [ ] Typography, surfaces, buttons, cards, and status indicators are documented.
* [ ] Responsive and accessibility requirements are documented.
* [ ] Reduced-motion behavior is documented.
* [ ] Contributor styling rules are documented.
* [ ] Existing project structure and styling responsibilities are preserved.
* [ ] The guide does not introduce an unrelated design system or application architecture.
* [ ] The documentation clearly communicates Arbellar's futuristic, secure, non-custodial DeFi visual direction.

---

## Verification

Review the final `STYLE-GUIDE.md` against the current Arbellar-Frontend repository structure.

Verify that:

```bash
pnpm lint
pnpm type-check
pnpm build
```

continue to pass if these scripts are available in the project.

Confirm that all documented file paths, theme tokens, naming conventions, and implementation references match the actual project structure.

## Suggested Branch

```text
docs/arbellar-style-guide
```

## Suggested Commit

```text
docs(frontend): add Arbellar global style guide
```


Uh oh!

feat(frontend): Create Global Arbellar-Frontend Style Guide #3

Description

Description

Scope

Light/Dark Mode

Source of Truth

Default Theme

Files & Directories

Theme Initialization

Global Theme State

Theme Toggle

Global CSS

Tailwind Configuration

Arbellar Visual Direction

Global Theme Tokens

Primary Colors

Medium-Dark Teal

Light Glow Teal

Stellar Yellow

Supporting Colors

Dark Background

Alternative Dark Surface

Primary Foreground

Muted Foreground

Dark Teal

Light Teal

Yellow Hover

Dark Yellow

Color Usage Rules

Glow Effects

Typography

Backgrounds & Surfaces

Buttons & Interactive Elements

Cards & Panels

Status & Financial Indicators

Responsive Design

Accessibility

Animation & Motion

Contributor Rules

1. Use centralized theme tokens

2. Use dark: for theme-specific styling

3. Access theme through the theme context

4. Avoid arbitrary visual styles

5. Preserve visual consistency

Security & Trust Visual Principles

Acceptance Criteria

Verification

Suggested Branch

Suggested Commit

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

2. Use `dark:` for theme-specific styling