# AGENTS.md

# Concise UI Design Philosophy

Concise UI is a Vue component framework designed for **enterprise and productivity software**.

The goal is **not** to imitate Material Design, Bootstrap, mobile-first design, or flashy dashboards. The goal is to maximize usability, readability, and information density for desktop business applications.

Think:

- WinForms philosophy
- Modern web technology
- Professional enterprise appearance

---

# Core Principles

## Information Density
Every pixel should have a purpose.
Avoid excessive whitespace.
Interfaces should comfortably display many controls without feeling cramped.

Target use cases:
- ERP
- WMS
- CRM
- POS
- Finance
- Inventory
- Internal company systems
- Admin panels

Not:
- Marketing landing pages
- Portfolio websites
- Mobile-first applications

---

## Modern Appearance
Do NOT copy old WinForms visually.

Instead:
- clean
- flat
- subtle
- modern

Avoid:
- glossy gradients
- skeuomorphic effects
- excessive shadows
- oversized rounded corners

---
## Conservative Color Usage
Color communicates meaning.
Do not color everything.
Use color primarily for:
- Primary actions
- Success
- Warning
- Error
- Selection
- Focus

Most controls should remain neutral.

---

## Compact Components

Components should be intentionally compact.

Preferred defaults:
- Font: 13–14px
- Control height: ~30–32px
- Small paddings
- Tight spacing
- Small border radius

Avoid large mobile-oriented controls.

---

## Clear Visual Hierarchy
Hierarchy should come from:
- spacing
- typography
- borders

Not from giant cards or colorful backgrounds.

---

## Functional Borders
Borders are encouraged.
Inputs should always be visually distinguishable.
Panels may have subtle borders.
Tables should clearly separate rows and columns.

---

## Minimal Decoration
Avoid decoration unless it improves usability.
Examples:
Good
- subtle hover
- subtle focus ring
- subtle elevation

Avoid
- animations for decoration
- glowing effects
- floating cards everywhere
- unnecessary transitions
---

## Desktop First
Primary target:
Desktop users with keyboard and mouse.
Touch support is secondary.
Keyboard accessibility is first-class.
---

## Performance
Components should remain lightweight.
Avoid unnecessary dependencies.
Prefer native browser capabilities.
Tree-shaking should be supported.
---

## API Philosophy
APIs should be:
- predictable
- explicit
- consistent

Example:

```vue
<CButton />
<CInput />
<CCheckbox />
<CDialog />
<CDataTable />
```
Naming should remain consistent across the framework.
---

# Creating a New Component

Use this checklist whenever adding a public Concise UI component.

1. Define the component contract before implementation:
   - purpose and expected behavior
   - props, events, slots, and `v-model` shape
   - disabled, loading, empty, invalid, or indeterminate states where relevant
   - mouse and keyboard behavior
2. Create the component under `src/components/<kebab-name>/C<ComponentName>.vue`.
3. Add `types.ts` beside the component when it has reusable public types. Reuse existing shared types, such as form-control sizes, instead of duplicating them.
4. Follow the established implementation style:
   - Vue 3 `<script setup lang="ts">`
   - scoped SCSS with a `.c-*` root class
   - compact dimensions and theme CSS variables
   - no new dependency when native Vue, HTML, or CSS is sufficient
5. Implement accessibility as part of the component:
   - native semantics where possible
   - appropriate roles and ARIA state otherwise
   - labels or accessible-name support
   - keyboard navigation for interactive components
   - reduced-motion handling for meaningful animations
6. Export the component from `src/index.ts`. Export its public TypeScript types there as well.
7. Create a documentation page under `src/pages/components/<ComponentName>.vue` containing:
   - a short purpose statement
   - live examples for primary behavior
   - important states, sizes, and variants
   - JavaScript and Vue usage through `CCodeBlock` where useful
   - a properties, events, and slots reference
8. Register the documentation route in `src/router/index.ts`.
9. Add the page to both component-navigation lists in `src/layouts/useLayoutNavigation.ts`, including its active state and route command.
10. Review the complete change for API consistency, accessibility, compact presentation, documentation accuracy, and accidental unrelated edits. At minimum, run `git diff --check`.

For example, creating `CProgressBar` includes the component and public types, determinate and indeterminate behavior, optional value text, semantic variants, sizes, accessibility, documentation, routing, navigation, and public exports.

---

# Themes
Themes should modify only presentation.
Themes should NOT change:
- component behavior
- spacing philosophy
- sizing philosophy

Initial themes:
- Concise Light
- Concise Dark

Future themes may include:
- Classic
- High Contrast

---

# What Concise UI Is
- Efficient
- Compact
- Professional
- Enterprise-oriented
- Keyboard-friendly
- Productivity-focused

---

# What Concise UI Is NOT
- Material Design clone
- Bootstrap clone
- Tailwind component library
- Mobile-first framework
- Marketing website toolkit
- Highly animated UI library

---
# Decision Rule
When multiple implementations are possible, prefer the one that improves:
1. Productivity
2. Readability
3. Information density
4. Consistency
5. Simplicity

Even if it is slightly less visually trendy.