diff --git a/brandGuidelinesSidebars.js b/brandGuidelinesSidebars.js new file mode 100644 index 000000000..20606757c --- /dev/null +++ b/brandGuidelinesSidebars.js @@ -0,0 +1,96 @@ +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + tutorialSidebar: [ + { + type: 'doc', + id: 'index', + label: 'Overview' + }, + { + type: 'category', + label: 'Brand Foundation', + items: [ + { + type: 'doc', + id: 'brand_foundation/dna_mission/index', + label: 'DNA & Mission' + }, + { + type: 'doc', + id: 'brand_foundation/buyer_persona/index', + label: 'Buyer Persona' + } + ] + }, + { + type: 'category', + label: 'Voice & Communication', + items: [ + { + type: 'doc', + id: 'voice_communication/tone_of_voice/index', + label: 'Tone of Voice' + } + ] + }, + { + type: 'category', + label: 'Visual Identity', + items: [ + { + type: 'doc', + id: 'visual_identity/logo/index', + label: 'Logo' + }, + { + type: 'doc', + id: 'visual_identity/color_system/index', + label: 'Color System' + }, + { + type: 'doc', + id: 'visual_identity/typography/index', + label: 'Typography' + }, + { + type: 'doc', + id: 'visual_identity/elevation/index', + label: 'Elevation' + } + ] + }, + { + type: 'category', + label: 'Design System', + items: [ + { + type: 'doc', + id: 'design_system/iconography/index', + label: 'Iconography' + }, + { + type: 'doc', + id: 'design_system/spacing_grid/index', + label: 'Spacing & Grid' + }, + { + type: 'doc', + id: 'design_system/components/index', + label: 'Components' + }, + { + type: 'doc', + id: 'design_system/layout/index', + label: 'Layout' + }, + { + type: 'doc', + id: 'design_system/interaction_behavior/index', + label: 'Interaction & Behavior' + } + ] + } + ] +}; + +module.exports = sidebars; diff --git a/brand_guidelines/brand_foundation/buyer_persona/buyer.png b/brand_guidelines/brand_foundation/buyer_persona/buyer.png new file mode 100644 index 000000000..bb4b15726 Binary files /dev/null and b/brand_guidelines/brand_foundation/buyer_persona/buyer.png differ diff --git a/brand_guidelines/brand_foundation/buyer_persona/index.mdx b/brand_guidelines/brand_foundation/buyer_persona/index.mdx new file mode 100644 index 000000000..41240f3bb --- /dev/null +++ b/brand_guidelines/brand_foundation/buyer_persona/index.mdx @@ -0,0 +1,50 @@ +# Buyer Persona + +
+ Alex Thompson - Primary buyer persona +
+

Alex Thompson

+

Age: 35–40

+

Location: Silicon Valley, CA

+

+ Job Title: Senior Software Engineer / Tech Lead +

+

+ Company Type: Tech company (SaaS / Cloud / AI) +

+
+ +
+ +> "I want tools that are clear, reliable, and integrate with my workflow — without wasting time on clutter." + +### Goals and motivation + +- Save time and reduce cognitive load +- Reliable, scalable tools for enterprise needs +- Integrate smoothly with existing workflows +- Professional growth & high-impact projects + +### Challenges and pain points + +- Cluttered or inconsistent UIs +- Overloaded with information → needs clear, fast access +- Skeptical of flashy marketing → prefers data-driven proof +- Tools must fit developer habits → minimal onboarding + +### UX preferences + +- Minimalist, clean interfaces +- Dark/light mode options +- Predictable navigation +- Functional icons over decorative elements diff --git a/brand_guidelines/brand_foundation/dna_mission/index.mdx b/brand_guidelines/brand_foundation/dna_mission/index.mdx new file mode 100644 index 000000000..0dd2d8613 --- /dev/null +++ b/brand_guidelines/brand_foundation/dna_mission/index.mdx @@ -0,0 +1,35 @@ +# DNA & Mission + +_This section is ready for your brand DNA and mission content._ + +## Core values + +We are a company built on **hard work**, **excellence**, and **honesty**. No fluff, no gimmicks — just powerful tools that let teams focus on what matters. We believe in solving real problems with precision, not spinning around limitations or unnecessary complexity. Our ethos is simple: build smart, work hard, ship excellent results. + +## Mission + +We provide a powerful job orchestrator designed for enterprise teams. Our platform comes with built-in editors that let you create scripts, flows, and apps — and deploy them seamlessly — without worrying about dependencies, scalability, or hidden constraints. +Unlike typical no-code tools that hit limits quickly, our solution is code-first: fully flexible, fully capable. Every “brick” is code, meaning your workflows, automations, and internal apps are limitless, robust, and future-proof. + +Mission Statement: + +- To empower companies to focus on what their tools do, not how they work. + +Value Proposition: + +- Efficiency: remove implementation headaches +- Scalability: no limits, enterprise-ready +- Control: full code power, minimal friction + +## What defines us + +| We are... | We are not... | +| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| ✓ Built on hard work and excellence — Every line of code, every feature, every decision reflects our commitment to quality | ✗ Marketing-heavy with flashy promises — We don't oversell capabilities or hide limitations behind buzzwords | +| ✓ Honest and transparent — We tell you exactly what our tools can do, when they'll be ready, and how they'll help | ✗ Focused on vanity features — We won't add complexity just to have more bullet points on a feature list | +| ✓ Problem solvers with precision — We identify real pain points and engineer elegant solutions that actually work | ✗ Compromise-makers on core functionality — We'd rather ship fewer features that work perfectly than many that work poorly | +| ✓ Focused on what matters — We build tools that let teams concentrate on their core objectives, not fight with software | ✗ Trend-chasers — We adopt new technologies when they solve real problems, not because they're popular | +| ✓ Performance-driven — Our tools are fast, reliable, and built to scale with your growing needs | ✗ Quick-fix merchants — We don't promise overnight transformations or magic solutions | +| ✓ Developer-first thinkers — We understand technical workflows and build for the people who live in code | ✗ Feature-factory oriented — We won't ship half-baked features just to meet arbitrary deadlines | +| ✓ Straightforward communicators — Clear documentation, honest timelines, and direct feedback | ✗ Hiding behind complexity — If something is hard to use, we fix the tool, not write longer documentation | +| ✓ Continuously improving — We iterate based on real usage, not trends or assumptions | ✗ Satisfied with "good enough" — We push for excellence even when the current version works fine | diff --git a/brand_guidelines/brand_foundation/index.mdx b/brand_guidelines/brand_foundation/index.mdx new file mode 100644 index 000000000..57eb75064 --- /dev/null +++ b/brand_guidelines/brand_foundation/index.mdx @@ -0,0 +1,11 @@ +# Brand Foundation + +This section covers the fundamental elements that define your brand identity and target audience. + +## Overview + +The brand foundation includes: +- DNA & Mission: Core values, mission statement, and brand personality +- Buyer Persona: Target user profiles and their characteristics + +Use the navigation on the left to explore each subsection and add your specific brand foundation content. \ No newline at end of file diff --git a/brand_guidelines/design_system/components/index.mdx b/brand_guidelines/design_system/components/index.mdx new file mode 100644 index 000000000..a641061c5 --- /dev/null +++ b/brand_guidelines/design_system/components/index.mdx @@ -0,0 +1,94 @@ +--- +title: Components +description: Component library usage rules and guidelines for Windmill developers +--- + +import ButtonShowcase from '@site/src/components/guidelines/ButtonThemeToggle'; + +# Components + +## Core Rules + +### 1. Always Use the Component Library + +**Never create custom components.** Use only the provided components from Windmill's library. If you need functionality that doesn't exist, request it from the design system team. + +### 2. No Style Hacking + +**Do not override component styles.** Components provide props for all supported variants and configurations. If you need a different appearance, use the appropriate prop variant. + +```jsx +// ✅ Correct - use provided variants + + +// ❌ Wrong - don't add custom styles + +``` + +### 3. Check Guidelines First + +**Always consult these component guidelines** before implementing. Each component section specifies: + +- When to use each variant +- Proper implementation patterns +- Accessibility requirements +- Common mistakes to avoid + +## Quick Reference + +### Before You Code + +1. Check if a component exists for your use case +2. Read the component's specific guidelines +3. Use only the documented props and variants +4. Test accessibility with keyboard navigation + +## Component Reference + +| Component | When to Use | Examples | +| ----------------------------- | --------------------------------------------------- | -------------------------------------------------- | +| **[Button.svelte](#buttons)** | User actions, form submissions, navigation triggers | Save, Cancel, Submit, Create, Edit, Delete | +| **Toggle.svelte** | Binary state changes, enable/disable features | Dark mode, notifications, auto-save, feature flags | + +--- + +## Buttons + +Windmill uses **4 button types** with clear hierarchy. Each button type comes in 3 variants (text, icon+text, icon-only) and supports multiple states including hover, active, disabled, and selected (default and subtle only). + + + +**Button Hierarchy:** + +- **Accent Secondary** (Highest Priority): Main conversion CTAs on landing pages - "Sign up", "Get started", "Download" +- **Accent** (High Priority): Most important action per view - "Save", "Submit", "Create" (only one per screen) +- **Default** (Standard Priority): Secondary actions and most UI interactions - "Cancel", "Edit", "Delete" +- **Subtle** (Low Priority): Tertiary actions in dense interfaces - toolbars, button groups + +**Button States:** + +- **Default**: Standard button appearance +- **Hover**: Interactive feedback when cursor hovers over button +- **Active/Pressed**: Visual feedback when button is clicked or pressed +- **Disabled**: Non-interactive state for unavailable actions +- **Selected**: Active selection state (available only for Default and Subtle variants) + +**Usage Rules:** + +- ✅ Use appropriate hierarchy, provide tooltips for icon-only buttons, test all states including disabled and selected +- ❌ Don't use multiple Accent buttons per view, use Accent Secondary outside marketing, create custom styles, or use selected state on Accent variants + +## Form Components + +Form components are currently being redesigned and will be documented here when ready. + +--- + +## Implementation Notes + +When implementing any component: + +1. **Follow the design system**: Use only the components and variants documented here +2. **Accessibility first**: All components include built-in accessibility features +3. **Test thoroughly**: Verify functionality across different states and themes +4. **Ask questions**: When in doubt, consult the design system team before creating custom solutions diff --git a/brand_guidelines/design_system/iconography/index.mdx b/brand_guidelines/design_system/iconography/index.mdx new file mode 100644 index 000000000..a20d97415 --- /dev/null +++ b/brand_guidelines/design_system/iconography/index.mdx @@ -0,0 +1,41 @@ +--- +title: Iconography +description: Icon library and usage guidelines for Windmill interfaces +--- + +# Iconography + +We use the **[Lucide icon library](https://lucide.dev/)** to ensure a consistent, modern, and lightweight visual language. Icons are line-only, aligning with our clean and technical aesthetic. + +## Why Lucide? + +Lucide provides consistent 2px stroke width, rounded joins, and professional quality across 1,000+ icons. All icons share the same 24x24 grid system and line-only style. + +## Sizing + +- **16px**: Table cells, compact interfaces +- **20px**: Form inputs, button icons +- **24px**: Navigation, primary actions +- **32px**: Feature highlights, empty states + +## Do's and Don'ts + +### ✅ Do + +- Use Lucide icons consistently throughout the interface +- Maintain the original 2px stroke width and style +- Use semantic colors from our color system +- Pair icons with text labels when possible +- Use standard sizes (16px, 20px, 24px, 32px) +- Ensure sufficient contrast for accessibility + +### ❌ Don't + +- Mix different icon libraries or styles +- Modify the stroke width or visual style +- Use icons as pure decoration without function +- Use icons alone for complex or uncommon actions +- Scale icons to arbitrary sizes +- Create custom icons unless absolutely necessary + +Icons should enhance usability and clarity, not complicate the interface. When in doubt, prioritize clear text labels over icons alone. \ No newline at end of file diff --git a/brand_guidelines/design_system/index.mdx b/brand_guidelines/design_system/index.mdx new file mode 100644 index 000000000..96a35f822 --- /dev/null +++ b/brand_guidelines/design_system/index.mdx @@ -0,0 +1,14 @@ +# Design System + +This section covers the complete design system including components, layouts, and interaction patterns. + +## Overview + +Design System includes: +- Iconography: Icon library and usage guidelines +- Spacing & Grid: Layout fundamentals and spacing scales +- Components: Reusable UI components and specifications +- Layout: Page structure and content organization principles +- Interaction & Behavior: Animation principles and micro-interactions + +Use the navigation on the left to explore each subsection and add your specific design system content. \ No newline at end of file diff --git a/brand_guidelines/design_system/interaction_behavior/index.mdx b/brand_guidelines/design_system/interaction_behavior/index.mdx new file mode 100644 index 000000000..d2a09903c --- /dev/null +++ b/brand_guidelines/design_system/interaction_behavior/index.mdx @@ -0,0 +1,15 @@ +# Interaction & Behavior + +*This section is ready for your interaction and behavior guidelines.* + +## Suggested Content Structure + +- Animation principles and timing +- Micro-interactions and hover states +- Transition guidelines +- Loading states and feedback +- User feedback patterns +- Accessibility considerations for interactions +- Implementation examples and code + +Add your specific interaction and behavior guidelines here. \ No newline at end of file diff --git a/brand_guidelines/design_system/layout/index.mdx b/brand_guidelines/design_system/layout/index.mdx new file mode 100644 index 000000000..2487a6330 --- /dev/null +++ b/brand_guidelines/design_system/layout/index.mdx @@ -0,0 +1,109 @@ +--- +title: Layout +description: Layout guidelines and patterns for consistent user interface design +--- + +import ExampleImageDisplay from '@site/src/components/guidelines/ExampleImageDisplay'; + +# Layout + +Our layout system ensures **consistency, clarity, and usability** across all interfaces. These guidelines establish standardized patterns for organizing content and interface elements. + +## Form + +Forms are fundamental building blocks of our application. They should be clear, efficient, and follow consistent patterns to reduce cognitive load and improve user experience. + +### Design Principles + +- **Predictable structure**: Consistent vertical hierarchy helps users scan and complete forms efficiently +- **Clear communication**: Every element serves a purpose in guiding users toward successful completion +- **Minimal cognitive load**: Use established patterns and clear visual hierarchy +- **Accessible by default**: Follow semantic HTML and proper labeling conventions + +### Vertical Layout Guidelines + +All form elements follow a consistent top-to-bottom hierarchy: + +**Label → Description → Input → Validation/Hint** + +This predictable order allows users to quickly understand what information is needed and how to provide it correctly. + +### Spacing Guidelines + +Use consistent spacing to create clear relationships between form elements: + +- **4px gap (`gap-y-1`)** between all adjacent form elements: + - Label to Description + - Description to Input + - Input to Validation/Hint + +This tight, consistent spacing groups related elements while maintaining clear separation between form fields. + +### Typography Guidelines + +Follow our established [typography system](../../visual_identity/typography/index.mdx) for form elements: + +#### Label +- **Style**: Body emphasized (`text-xs font-medium text-emphasis`) +- **Purpose**: Clearly identify what information is required +- **Example**: "Job name:", "Resource type:", "Environment variables:" + +#### Description +- **Style**: Body (`text-xs font-normal text-primary`) +- **Purpose**: Provide additional context or instructions +- **Example**: "Choose a descriptive name for your automation job" + +#### Validation/Hint +- **Style**: Caption (`text-2xs font-normal text-secondary`) +- **Purpose**: Guide users with requirements or feedback +- **Example**: "Required field", "Must be at least 8 characters", "Optional field" + +### Writing Guidelines + +#### Descriptions +- Keep descriptions concise and actionable +- Focus on the outcome or benefit, not the technical process +- Use sentence case and avoid unnecessary punctuation +- Example: ✅ "Choose the Python version for your script execution" vs ❌ "This dropdown allows you to select which Python version will be used when executing your script." + +#### Helper Text and Hints +- Be specific about requirements upfront +- Use positive language when possible +- Provide examples for complex inputs +- Example: ✅ "Use lowercase letters, numbers, and hyphens only" vs ❌ "Invalid characters not allowed" + +### Tooltip Usage + +Use tooltips sparingly for **additional context** that would otherwise clutter the interface: + +- Complex terminology or concepts that need definition +- Background information that helps with decision-making +- Links to relevant documentation or resources + +**Don't use tooltips for**: +- Essential information needed to complete the form +- Error messages or validation feedback +- Basic instructions that should be in the description + +### Visual Example + + + +The example above demonstrates: +- Clear label hierarchy using Body emphasized typography +- Concise description text using Body typography +- Consistent 4px spacing between all elements +- Proper input field styling +- Caption-styled hint text below the input + +### Implementation Notes + +- Always include proper semantic HTML (`