neo4j-styleguide

Ensure consistency with Neo4j brand identity, the Needle design system, and Cypher coding conventions.

Brand Colors

Primary: Baltic (Blue-Green Teal)

The primary color is inspired by the Baltic Sea, combining calmness of blue with refreshing green qualities. It has both cool and warm undertones.

Primary Teal:    #018BFF (bright blue), #009999 (teal), #00C1B6 (cyan)

Secondary Palette (Nature-Inspired)

Green:           #2F9E44 (forest), #B2F2BB (light green)
Orange:          #F79767 (warm orange), #FFEC99 (light yellow)
Red:             #E03131 (alert red), #FFC9C9 (light red)
Purple:          #C990C0 (node purple), #D0BFFF (light purple)
Pink:            #DA7194 (relationship pink)

Neutral Colors

Dark:            #1E1E1E (text black)
Gray:            #A5ABB6 (default node/relationship)
Light:           #F3F3F0 (background)
White:           #FFFFFF

Typography

Font Families

| Use Case | Font | Notes | |----------|------|-------| | Display/Headings | Syne Neo | Modified Syne with circular dots (not squares) in periods, tittles. Rounded 'g' descender. | | Body Text | Public Sans | Narrow structure, high legibility, good contrast to Syne | | Code/Monospace | Letter Gothic | For code samples, Cypher queries, technical content |

Typography Guidelines

• Use Syne Neo sparingly for headlines and display text
• Public Sans for all body copy and UI text
• Code blocks always use monospace font
• Ensure adequate contrast for accessibility

Node Shape Language

Neo4j uses organic, fluid node shapes based on a hexagonal grid:

• Circles/Ellipses for entity nodes
• Rounded rectangles for containers/components
• Avoid rigid, angular shapes
• Shapes should feel interconnected and organic

Cypher Code Style

Naming Conventions

| Element | Convention | Example | |---------|------------|---------| | Keywords | UPPERCASE | MATCH, RETURN, CREATE, WHERE | | Node Labels | UpperCamelCase | :Person, :Movie, :Organization | | Relationship Types | UPPER_SNAKE_CASE | :ACTED_IN, :WORKS_AT, :KNOWS | | Properties | lowerCamelCase | firstName, dateCreated, isActive | | Variables | lowercase | n, m, p, person, movie | | Null/Boolean | lowercase | null, true, false |

Formatting Rules

// Keywords uppercase, proper spacing
MATCH (p:Person {name: 'Alice'})-[:KNOWS]->(friend:Person)
WHERE friend.age > 30
RETURN friend.name AS name, friend.age AS age
ORDER BY friend.age DESC

Key rules:

• No space in label predicates: (n:Label) not (n: Label)
• Space after commas in lists
• No padding in function calls: count(n) not count( n )
• Break long patterns after arrows, not before
• Use anonymous nodes when variable not needed: ()-->(n:Movie)
• Chain patterns to avoid repeating variables

File Extension

Use .cypher for Cypher query files.

Documentation Writing

In Prose References

When referencing Cypher constructs in documentation:

• Labels with colon: :Person, :Movie
• Relationship types with colon: :ACTED_IN, :KNOWS
• Functions with parentheses: count(), toString(), collect()
• Use monospace/code font for all Cypher elements
• Use cypherfmt (Neo4j VS Code Extension) for formatting

Code Examples

Always include:

• Proper syntax highlighting
• Realistic, meaningful sample data
• Comments explaining non-obvious patterns

Graph Visualization Colors

Default node label colors for Neo4j Browser/Bloom:

node {
  color: #A5ABB6;        /* default gray */
  border-color: #9AA1AC;
  text-color-internal: #FFFFFF;
}

node.Person {
  color: #DA7194;        /* pink */
  border-color: #CC3C6C;
}

node.Movie {
  color: #C990C0;        /* purple */
  border-color: #B261A5;
}

node.Organization {
  color: #F79767;        /* orange */
  border-color: #F36924;
}

relationship {
  color: #A5ABB6;
  shaft-width: 1px;
}

Diagram Guidelines

When creating diagrams for Neo4j content:

1. Use organic shapes - circles for nodes, curved arrows for relationships
2. Apply brand colors - use the Baltic teal as primary accent
3. Show relationships clearly - arrows with type labels
4. Include properties - show key properties inside node shapes
5. Maintain whitespace - don't overcrowd diagrams

Excalidraw Integration

When using the excalidraw skill for Neo4j diagrams:

• Use #009999 (teal) for primary/highlighted nodes
• Use #A5ABB6 (gray) for secondary nodes
• Use distinct colors for different node labels
• Label relationships in UPPER_SNAKE_CASE
• Use hand-drawn style (roughness: 1) for approachable feel

AI-Generated Illustrations

Neo4j has specific guidelines for AI-generated artwork:

• Define a consistent illustration style
• Use the brand color palette in prompts
• Avoid generic AI aesthetics
• Maintain organic, nature-inspired themes
• Focus on connections and relationships

Quick Reference

Primary:     #009999 (Baltic teal)
Accent:      #00C1B6 (cyan)
Text:        #1E1E1E (dark)
Background:  #F3F3F0 (light)

Display:     Syne Neo
Body:        Public Sans  
Code:        Letter Gothic

Labels:      UpperCamelCase (:Person)
Rel Types:   UPPER_SNAKE_CASE (:WORKS_AT)
Properties:  lowerCamelCase (firstName)
Keywords:    UPPERCASE (MATCH, RETURN)

Resources

• Needle Design System: https://neo4j.design
• Cypher Style Guide: https://neo4j.com/docs/cypher-manual/current/styleguide/
• Naming Conventions: https://neo4j.com/docs/cypher-manual/current/syntax/naming/
• Browser Styling: https://neo4j.com/docs/browser-manual/current/operations/browser-styling/