Dokumentation

Appearance

Hermeneus Application Style Guide ​

A comprehensive style guide for the entire Hermeneus application, based on analysis of Vue components and established design patterns.

1. General Structure and Layout ​

1.1 Container and Wrapper Patterns ​

  • Main Container: flex flex-col bg-white p-4 w-full
  • Page Layout: Two-column layout with flex flex-row justify-between
    • Main content (left): w-1/2 or w-2/3
    • Sidebar/Settings (right): w-1/3 ml-8
  • Section Spacing: my-3 for vertical spacing between sections
  • Card Containers: bg-white rounded-lg shadow-sm border border-grey-200 p-6

1.2 Responsive Design ​

  • Breakpoint Prefixes:
    • sm-minus: - Small screens and below
    • md-plus: - Medium screens and above
  • Mobile-First Approach: Default styles for mobile, enhance for larger screens
  • Example: sm-minus:w-full md-plus:w-2/5

2. Typography ​

2.1 Font Families ​

  • Latin Text: Always font-serif font-bold
  • Default Text: Sans-serif (system default)
  • Monospace: For code snippets and technical content
  • Special Cases: Grammatical information in italic

2.2 Font Sizes ​

  • Page Titles (h1): text-4xl or text-5xl
  • Section Headers (h2): text-3xl font-bold
  • Subsection Headers (h3): text-xl font-bold
  • Card Headers: text-lg font-semibold
  • Body Text: text-base or text-lg
  • Labels: text-sm font-medium or font-bold
  • Helper Text: text-sm or text-xs
  • Fine Print: text-xs

2.3 Text Colors ​

  • Primary Text: text-primary-900 or text-grey-900
  • Secondary Text: text-grey-700 or text-grey-600
  • Muted Text: text-grey-500
  • Success States: text-success-600 or text-success-dark
  • Error States: text-danger-600 or text-danger-dark
  • Warning States: text-warning-600 or text-warning-dark
  • Info States: text-info-dark
  • Links: text-primary-600 hover:text-primary-700

3. Color Palette ​

3.1 Primary Colors ​

  • Primary:
    • Light: primary-50, primary-100
    • Main: primary-500, primary-600
    • Dark: primary-700, primary-800, primary-900
    • Usage: Main brand color, primary actions, active states
  • Secondary:
    • Legacy: secondary_color
    • Modern: secondary-500
    • Usage: Secondary actions, accents

3.2 Status Colors ​

  • Success:
    • Background: bg-success-50, bg-success-100, bg-success-light
    • Border: border-success, border-success-500, border-success-dark
    • Text: text-success-600, text-success-dark
  • Danger/Error:
    • Background: bg-danger-50, bg-danger-100
    • Border: border-danger-500
    • Text: text-danger-600, text-danger-dark
  • Warning:
    • Background: bg-warning-50, bg-warning-light
    • Border: border-warning-300
    • Text: text-warning-600, text-warning-dark, text-warning2-dark
  • Info:
    • Background: bg-info-light
    • Border: border-info
    • Text: text-info-dark

3.3 Neutral Colors ​

  • Grey Scale:
    • Backgrounds: bg-grey-50 to bg-grey-900
    • Common: bg-grey-100 (light), bg-grey-200 (medium), bg-grey-400 (disabled)
    • Borders: border-grey-200 (subtle), border-grey-300 (default), border-grey-400 (strong)
  • White: bg-white for cards and content areas
  • Black: Used sparingly for high contrast

4. Component Patterns ​

4.1 Cards and Panels ​

css
/* Standard Card */
bg-white rounded-lg shadow-sm border border-grey-200 p-6
hover:shadow-md transition-shadow

/* Elevated Card */
bg-white rounded-lg shadow-md p-6

/* Flat Card */
bg-grey-50 rounded-lg p-6

4.2 Form Elements ​

Input Fields ​

  • Standard Input: input-light p-2 w-full
  • PrimeVue InputText: <InputText class="w-full" />
  • Textarea: textarea-light p-2 w-full or <Textarea :autoResize="true" />
  • States:
    • Focus: focus:border-primary-500
    • Error: border-danger-500
    • Success: border-success-500
    • Disabled: opacity-50 cursor-not-allowed

Labels ​

  • Standard Label: mb-2 ml-1 text-primary-900 font-bold
  • Required Field: Add * after label text
  • With Description:
    html
    <label class="mb-2 ml-1 text-primary-900 font-bold">
  Label Text
  <span class="block text-sm font-light">Helper description</span>
</label>

Buttons ​

  • PrimeVue Button (Preferred):
    html
    <Button label="Primary" severity="primary" />
<Button label="Secondary" severity="secondary" />
<Button label="Success" severity="success" />
<Button label="Danger" severity="danger" />
<Button label="Small" size="small" />
<Button label="With Icon" icon="fas fa-check" />
  • Custom Button: bg-primary-600 hover:bg-primary-700 text-white rounded px-4 py-2
  • Icon Button: text-grey-500 hover:text-primary-600 p-2

4.3 Navigation Components ​

  • Main Navigation: Dark theme with bg-primary-800 or bg-primary-900
  • Breadcrumbs: text-sm text-grey-600 with > separators
  • Tabs: Border-bottom style with active indicator
  • Sidebar: bg-grey-50 with border-r border-grey-200

4.4 Data Display ​

Tables ​

  • Header: bg-grey-100 font-bold text-grey-700
  • Rows: border-b border-grey-200 hover:bg-grey-50
  • Cells: p-3 or p-4

Lists ​

  • Item Separator: border-b border-grey-200
  • Hover State: hover:bg-grey-50
  • Selected State: bg-primary-50 border-l-4 border-primary-500

5. Spacing System ​

5.1 Padding ​

  • Extra Small: p-1 (0.25rem)
  • Small: p-2 (0.5rem)
  • Medium: p-3 (0.75rem) or p-4 (1rem)
  • Large: p-6 (1.5rem) or p-8 (2rem)
  • Directional: px-4 py-2, pt-4 pb-2, etc.

5.2 Margin ​

  • Section Separation: my-8 or mt-8 mb-4
  • Element Spacing: mb-4 or mb-6
  • Inline Spacing: mr-2 or mr-3 for icons
  • Group Spacing: space-y-4 for vertical lists

5.3 Gap (Flexbox/Grid) ​

  • Tight: gap-2 (0.5rem)
  • Default: gap-3 (0.75rem) or gap-4 (1rem)
  • Wide: gap-6 (1.5rem) or gap-8 (2rem)

6. Icons ​

6.1 Icon Systems ​

  • FontAwesome: Primary icon library
    • Solid: fas fa-{icon-name}
    • Regular: far fa-{icon-name}
    • Brands: fab fa-{icon-name}
  • Hermeneus Icons: Custom icons
    • Usage: hi hi-{icon-name} or <hermeneus-icon name="hi-{icon-name}" />

6.2 Icon Sizing ​

  • Extra Small: text-sm
  • Small: text-lg or text-xl
  • Medium: text-2xl or height="32"
  • Large: text-3xl or text-4xl or height="48"
  • Extra Large: height="72"

6.3 Icon Colors ​

  • Hermeneus Component: Always use color="hi-color-primary-600"
  • FontAwesome: Apply Tailwind color classes directly

6.4 Icon Spacing ​

  • Before Text: mr-2 or mr-3
  • After Text: ml-2 or ml-3
  • Standalone: No additional spacing needed

7. Interactive States ​

7.1 Hover Effects ​

  • Links: hover:text-primary-700 hover:underline
  • Buttons: hover:bg-primary-700 (darker shade)
  • Cards: hover:shadow-md
  • List Items: hover:bg-grey-50
  • Transitions: Always add transition-all duration-200 or transition-{property}

7.2 Focus States ​

  • Inputs: focus:border-primary-500 focus:ring-2 focus:ring-primary-200
  • Buttons: focus:outline-none focus:ring-2 focus:ring-primary-500
  • Links: focus:outline-none focus:underline

7.3 Active/Selected States ​

  • Navigation: bg-primary-600 text-white
  • List Items: bg-primary-50 border-l-4 border-primary-500
  • Tabs: Border-bottom indicator

7.4 Disabled States ​

  • Opacity: opacity-50
  • Cursor: cursor-not-allowed
  • Background: bg-grey-100
  • Text: text-grey-400

8. Animations ​

8.1 Transitions ​

  • Default: transition-all duration-200
  • Fast: transition-all duration-100
  • Slow: transition-all duration-300
  • Specific Properties: transition-shadow, transition-colors, transition-transform

8.2 Transform Effects ​

  • Scale on Click: active:scale-95
  • Hover Lift: hover:-translate-y-1
  • Rotation: hover:rotate-3

8.3 Loading States ​

  • Spinner: fas fa-spinner fa-spin
  • Skeleton: <Skeleton height="2rem" /> (PrimeVue)
  • Custom Loaders:
    • <loading-dots> - Medium size, general purpose
    • <loading-dual-ring> - Small size, inline
    • <loading-comet> - Large size, page loads

8.4 Page Transitions ​

css
.slide-fade-enter-active { transition: all .3s ease; }
.slide-fade-leave-active { transition: all .3s ease; }
.slide-fade-enter, .slide-fade-leave-to {
  transform: translateY(10px);
  opacity: 0;
}

9. Layout Patterns ​

9.1 Page Layouts ​

  • Dashboard: Grid-based with cards
  • Form Pages: Centered container with max-width
  • List/Table Pages: Full width with filters on top
  • Detail Pages: Two-column with sidebar

9.2 Flexbox Utilities ​

  • Container: flex flex-col or flex flex-row
  • Alignment: items-center, items-start, items-end
  • Justification: justify-between, justify-center, justify-start
  • Wrapping: flex-wrap
  • Growth: flex-1, flex-grow, flex-shrink-0

9.3 Grid Utilities ​

  • Columns: grid grid-cols-2, grid-cols-3, grid-cols-4
  • Responsive: sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  • Gap: gap-4, gap-6

10. Messaging and Feedback ​

10.1 Toast Messages ​

javascript
this.$IrisMessenger.bar({
  type: 'success' | 'error' | 'warning' | 'info',
  message: 'Your message here',
  duration: 4000 // milliseconds
});

10.2 Alert Boxes ​

  • Info: bg-info-light border border-info rounded p-4
  • Success: bg-success-light border border-success rounded p-4
  • Warning: bg-warning-light border border-warning rounded p-4
  • Error: bg-danger-light border border-danger rounded p-4

10.3 Empty States ​

html
<div class="text-center py-12">
  <i class="fas fa-inbox text-6xl text-grey-400 mb-4"></i>
  <p class="text-grey-600">No items found</p>
</div>

11. Accessibility ​

11.1 Focus Management ​

  • Ensure all interactive elements are keyboard accessible
  • Provide visible focus indicators
  • Use tabindex appropriately

11.2 Color Contrast ​

  • Maintain WCAG AA compliance (4.5:1 for normal text, 3:1 for large text)
  • Don't rely solely on color to convey information

11.3 Screen Reader Support ​

  • Use semantic HTML elements
  • Provide meaningful labels and alt text
  • Use ARIA attributes when necessary

12. PrimeVue Integration ​

12.1 Preferred Components ​

  • Forms: InputText, Textarea, Select, Checkbox, RadioButton, ToggleSwitch
  • Buttons: Button (with severity and size props)
  • Data: DataTable, Paginator
  • Feedback: Toast, Message
  • Overlay: Dialog, Popover, Tooltip
  • Navigation: Stepper, TabView
  • Display: Badge, Chip, Tag
  • Loading: Skeleton, ProgressBar

12.2 Component Customization ​

  • Use component props over custom CSS
  • Apply Tailwind utilities via class prop
  • Override PrimeVue theme variables in root CSS

13. Best Practices ​

13.1 Consistency Rules ​

  • Always use design tokens (colors, spacing) instead of arbitrary values
  • Follow established patterns for similar components
  • Maintain consistent spacing throughout the application

13.2 Performance ​

  • Use Tailwind's purge feature in production
  • Lazy load heavy components
  • Optimize images and assets

13.3 Code Organization ​

  • Group related utility classes
  • Use component-scoped styles sparingly
  • Extract repeated patterns into components

13.4 Latin Text Formatting ​

  • Always apply font-serif font-bold to Latin words
  • Use spans for inline Latin: <span class="font-serif font-bold">lorem ipsum</span>
  • Add background colors for examples when needed

14. File Organization ​

14.1 CSS Structure ​

resources/css/
├── app.css (main entry point)
├── utilities.css (custom utilities)
├── components/ (component-specific styles)
├── layouts/ (layout patterns)
└── themes/ (theme overrides)

14.2 Component Structure ​

  • Keep styles close to components
  • Use CSS modules for component isolation
  • Follow single responsibility principle

This style guide serves as the foundation for maintaining visual consistency across the entire Hermeneus application. It should be regularly updated as new patterns emerge and the design system evolves.