🤖 Proposal: Agentic AI-Compatible Rule for Contributing to Flowbite Vue

[russor45]

Hi Flowbite Vue team 👋

I've authored a proposed Agentic Rule designed to standardize how components are created, tested, and documented for the Flowbite Vue project — with the specific goal of making contributions more consistent and compatible with Agentic AI workflows.

🎯 Why This Rule?

• Reflects your existing project conventions (naming, structure, styling)
• Adds structure for automated code generation incuding components, testing, accessibility, and documentation
• Enables developers (and AI agents) to programmatically contribute
• Built for use with tools like Roo Code or Cursor which enforces rules during generation and refactoring

Agentic workflows are rapidly gaining traction in frontend engineering. This rule would make Flowbite Vue an early adopter UI library to support this kind of scalable, automated contribution model — without changing anything about how the library works today.

Let me know your thoughts — happy to adapt this to fit the direction of the project or discuss how it could be integrated into the docs or contribution flow.

Thanks again for building such a clean and extensible component library — it's been a huge help in the agentic space! 🙌

📄 Proposed Coding Standards Document

Click to expand

## Flowbite Vue Coding Standards

### Objective

Build reusable, accessible Vue 3 components using **Flowbite’s design system**, **Tailwind CSS**, and the **Composition API**. Components must integrate with `flowbite-vue` and follow project standards.

> Note for contributors:
> **Always** generate code that fully complies with these standards and passes all linting, formatting, and style checks automatically.

---

### Project Structure

```text
flowbite-vue/
├── src/
│   ├── components/
│   │   ├── [ComponentName]/
│   │   │   ├── [ComponentName].vue
│   │   │   └── types.ts
│   ├── composables/
│   ├── tests/
│   │   └── [ComponentName].spec.ts
│   └── index.ts
├── docs/components/[component-name].md
├── docs/components/[component-name]/examples/[ComponentName]Example.vue

Naming

• Component files & folders: PascalCase (Button.vue, Modal/)
• Types/docs folders: kebab-case
• Props/emits: camelCase
• Component tags: kebab-case prefixed with fwb- (e.g., <fwb-button>)

---

1. Dependencies

• Declare flowbite and vue as peerDependencies:

  "peerDependencies": {
    "vue": "^3.3.0",
    "flowbite": "^2.2.0"
  }

• Assume flowbite is pre-installed in the consumer project.

• Use named ESM imports only — no global scripts or CDN reliance.

• Do not re-export flowbite modules.

• Externalize vue, flowbite, and other peers in bundler config.

• Use third-party libraries only when essential:

  • Use peerDependencies for optional/shared packages.
  • Use dependencies only for internal runtime needs.

• Favor small, internal utilities over large helper libraries.

---

2. Component Order

Use the following SFC block order:

• <template>
• <script>
• <style>

---

3. Composition API

• Use <script setup lang="ts">

• Define props/emits using defineProps and defineEmits with TypeScript types

• Prefer ref, computed, and watchEffect

• Avoid reactive unless deep reactivity is needed

• Guard browser-only APIs (window, document) for SSR support:

  if (typeof window !== 'undefined') {
    // Safe browser-only logic
  }

---

4. Tailwind + Flowbite Styling

• Use Tailwind CSS utility classes exclusively
• Apply Flowbite tokens, colors, and spacing utilities
• Accept class/:class props for wrapper customization
• Use clsx or twMerge to safely merge internal/external classes
• Use Tailwind’s dark: variant for dark mode — no runtime toggling

---

5. Interactivity & Flowbite JS

• Use data-* attributes from Flowbite (e.g., data-modal-toggle)

• Abstract behavior into composables like useDataAttribute

• If using Flowbite JS (e.g., Dropdowns), import ESM modules directly:

  import { Dropdown } from 'flowbite'

---

6. Accessibility

• Follow WAI-ARIA best practices

• Use semantic HTML with aria-*, role, tabindex, etc.

• Enable keyboard navigation

• Trap focus where needed (e.g., modals, drawers)

• Example:

  <div role="dialog" aria-modal="true" tabindex="-1">
    <!-- modal content -->
  </div>

---

7. Props & Emits

• Strongly type props and emits
• Provide default values and validations
• Emit events in kebab-case (e.g., update:model-value, open)
• Avoid naming collisions with native DOM events

---

8. Slots & Customization

• Use named slots (icon, header, footer)
• Provide fallback slot content
• Document available slots in the component .md file
• Avoid hardcoded text — expose via props or slots

---

9. Theming

• Use Tailwind's dark: variant for styling
• Align with Flowbite’s theme and color system
• Test components in both light and dark modes

---

10. Transitions

• Use Tailwind transitions (transition-opacity, duration-300, etc.)
• Use Vue’s <Transition> / <TransitionGroup>
• Avoid custom animations unless required
• Ensure transitions are smooth and accessible

---

11. Icons

• Accept icons via icon prop or <slot name="icon">
• Use Flowbite icon components where applicable
• Document expected icon structure and usage in .md file

---

12. Testing

• Use Vitest and @testing-library/vue
• Test rendering, props, events, slots, keyboard interaction
• Follow AAA structure (Arrange → Act → Assert)
• Use userEvent for interaction testing
• Avoid snapshot tests unless validating static HTML
• All tests must pass in CI (100% pass rate required)
• Example:

  it('renders button with default slot', () => {
    render(FwbButton, { slots: { default: () => 'Click me' } })
    expect(screen.getByRole('button')).toHaveTextContent('Click me')
  })

Note: Not all components have full test coverage yet. Contributions should include unit tests.

---

13. Documentation

• Create a .md file at docs/components/[component-name].md
• Reference the existing Flowbite Vue docs site.

Required .md File Sections Checklist

• Component name & description
• Usage examples ([ComponentName]Example.vue)
• Props table (name, type, default, required)
• Emits table (name, payload)
• Available slots
• Accessibility considerations

---

14. Naming & Import / Export

• Prefix component tags with fwb- (e.g., <fwb-modal>)
• Use kebab-case in templates
• Re-export all components from src/index.ts:

  export { default as FwbButton } from './components/Button/Button.vue'

• Optionally support auto-import via unplugin-vue-components with prefix fwb-

---

15. Code Style

• Use 2 spaces for indentation.
• Use single quotes for strings, unless escaping makes double quotes more readable.
• Use === and !== for comparisons.
• Prefer const over let, and avoid var.
• Use arrow functions for callbacks and function expressions.
• Add spaces around operators (e.g., a + b, x === y).
• Aim to keep lines under ~120 characters for readability.
• Break lines when it improves clarity (e.g., long props, class lists).
• Avoid empty lines between grouped imports.
• Do not add a space between function parentheses and braces (e.g., function foo() {).
• Add a blank line between class members.
• End every .vue, .js, and .ts file with a newline.
• Use trailing commas in multi-line arrays, objects, and imports.
• Use kebab-case for file names and PascalCase for component names (e.g., MyComponent.vue).
• Use self-closing tags for elements without children.

---

15a. Template Attribute Formatting

Maintain consistent and readable formatting in all <template> elements. These conventions are enforced by ESLint and must be followed to avoid lint errors.

Attribute Order (Top → Bottom)

Use the following order for attributes:

1. Vue directives (v-if, v-model, v-bind, v-on, :, @)
2. Global HTML attributes (id, type, name, value, etc.)
3. Class/style (class, :class, style)
4. ARIA/accessibility (role, aria-*, tabindex)
5. Data attributes (data-*)
6. Event listeners (@click, @change, etc.)

Line Formatting

• One attribute per line for multiline elements.
• Break to a new line after the opening tag when using multiple attributes.
• Do not self-close void elements like <input>, <img>, <br>, or <hr>.

Examples

✅ Correct:

<input
  v-model="value"
  type="text"
  class="form-input"
  aria-label="Input field"
  data-testid="main-input"
>

❌ Incorrect:

<input class="form-input" type="text" v-model="value" />

✅ SVG:

<svg
  class="icon"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  viewBox="0 0 24 24"
>
</svg>

Enforced Rules

These ESLint rules enforce this structure:

• vue/max-attributes-per-line
• vue/attributes-order
• vue/html-self-closing

Code that does not comply with these rules will fail linting and cannot be merged.

---

16. Error Handling

• Validate prop values
• Show developer warnings in non-production builds
• Avoid silent failures — fail predictably and clearly

---

17. Class Composition

• Allow class passthrough on root elements
• Use twMerge for merging user and internal styles
• Don’t hardcode classes where customization is expected

---

18. Linting & Tooling

The codebase uses ESLint to enforce code quality and maintain a consistent coding style across the project.

• ESLint with TypeScript and Vue 3 support
• eslint-plugin-vue using the vue3-recommended preset
• See .eslintrc.cjs in the project root for configuration details
• Run npm run lint before every commit and pull request.
• Configure your editor to display lint errors in real time.
• Generate code that passes all linting and formatting checks without manual fixes.
• No code (including tests, docs, and examples) should be merged with unresolved linting issues.

---

Component Checklist

• Vue 3 + <script setup lang="ts">
• Tailwind + Flowbite styles
• Strongly typed props & emits
• Accessible (ARIA, keyboard nav)
• Named slots + customization hooks
• Dark mode support (dark: variant)
• Fully tested (Vitest)
• Docs written (.md + examples)
• Exported via src/index.ts
• SSR & VitePress compatible
• Optimized for performance (lazy loading, efficient reactivity)
• Secure (no unsafe HTML, prop validation)
• Stable, warning-free in dev and production

---

Output Files

1. src/components/[ComponentName].vue — Main component

2. src/components/[ComponentName]/types.ts — Type declarations

   export interface ButtonProps {
     type?: 'button' | 'submit' | 'reset'
     disabled?: boolean
   }

3. src/index.ts — Public exports

4. tests/components/[ComponentName].spec.ts — Unit tests

5. docs/components/[component-name].md — Component documentation

6. docs/components/[component-name]/examples/[ComponentName]Example.vue — Usage example

Rule Type

This is a convention rule to guide component structure, syntax, and project integration. AI agents should treat this as a source of truth for generation, refactoring, and validation when working within a Flowbite Vue environment.

</details>