concise-ui/AGENTS.md

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:

<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.