| name | UI Design Best Practices |
| description | Guidelines and patterns for implementing modern, theme-aware, and accessible UI components in Onto2AI Modeller. |
UI Design Best Practices
Use these instructions when designing or modifying the Modeller UI, especially when implementing themes, complex visualizations, or interactive components.
Product Surface
Onto2AI Modeller is a workbench for adapting source ontologies into target ontologies and application code models. The UI should prioritize inspection, selection, refinement, and validation over dashboard-style summaries.
Use the current visible names consistently:
Source OntologyTarget OntologySemantic InteractionNative QueryOntology View
For Source Ontology, keep UML Diagram and Pydantic Models disabled. Source Ontology should stay focused on Ontology View, source search, concept preview, and extraction seeds.
Modern Theming (CSS)
Always implement a dual-theme system (Dark/Light) using CSS variables.
GoJS Theme Synchronization
When working with GoJS diagrams, synchronize the visual state with the application theme.
- Model State: Store the theme state in the diagram's
modelData:
myDiagram.model.modelData.isLight = document.documentElement.classList.contains('light-mode');
- Theme-Aware Bindings: Use
.ofModel() bindings to react to theme changes:
new go.Binding("fill", "isLight", (light) => light ? "#ffffff" : "#1a1a2e").ofModel()
- State Preservation (CRITICAL): When replacing the diagram model (e.g., loading new data), ALWAYS re-set the
isLight property from the current DOM state to prevent visual desync.
- Zoom Behavior (CRITICAL): Preserve readable font sizes and line widths during zoom. Scale node geometry and positions without letting text strokes become too small or too large.
- Viewport Stability (CRITICAL): Zoom in/out should keep the diagram centered on the user's visual focus. Avoid model replacement, layout re-run, or viewport reset during zoom interactions.
Contrast & Accessibility
Ensure all text and diagram elements provide sufficient contrast in both themes.
- Attributes & Datatypes: Use theme-aware colors for text.
- Light Mode: Dark green (
#065f46) for attribute names, slate (#475569) for types.
- Dark Mode: Bright green (
#34d399) for attribute names, light slate (#94a3b8) for types.
- Relationship Labels: For labels over lines (like "extends"), use a theme-aware background shape to ensure text remains readable regardless of the line color.
- Light Mode Background:
rgba(255, 255, 255, 0.9)
- Dark Mode Background:
rgba(15, 15, 26, 0.9)
UI Layout & Transitions
- Workbench Density: Favor navigator-style layouts with left catalog/search, center ontology view/detail, and right inspector/properties when the workflow involves browsing concepts.
- Glassmorphism: Use semi-transparent backgrounds sparingly. Do not let decorative style reduce legibility or density.
- Animations: Use micro-animations for hover states and transitions between views, but avoid motion that makes diagrams jump.
- Responsive Splitters: Use the
split.js pattern for resizable panels.
- URI Display: Treat URIs as unique identifiers. Display them as selectable text, not links, unless a surface is explicitly intended for web navigation.
- Configuration: LLM model lists and defaults should be populated from
onto2ai_modeller/config.yaml, not hard-coded in frontend code.
- LLM Errors: When chat fails, show provider, model, status/category, and a practical next action. Quota and missing-key failures should not look like generic chat failures.
Implementation Workflow
- Define/Update CSS variables in
styles.css.
- Implement theme toggle logic in
app.js.
- Update GoJS templates in
graph.js with theme bindings.
- Keep API response handling in sync with
onto2ai_modeller/api/schemas.py.
- Verify contrast, tab state, zoom stability, and text overlap in both modes using a browser check when UI behavior changes.
