eclipse-cdt-cloud / eclipse-cdt-cloud/theia-trace-extension

Create general design guidelines

Open
#151 4 comments 0 reactions 0 assignees View on GitHub
Theia UI UX
Dominant language
TypeScript
Stars
50
Forks
60
PR merge metrics
No merged PRs in 30d

Description

Create a document with style principles that apply to the whole project or several component types (ex. General layout principles, colour palette, UI component semantics).
* This helps create a cohesive and standardized tool.
* Guidelines can be adapted and improved as the project evolves and expertise is honed.
* (Guidelines specifically for graphs can be in a separate place.)

Prerequisite: Create chart style guidelines #152 before diving into defining these more abstract guidelines.

# Inspiration
Style guidelines can be strongly inspired by the VS Code and Grafana style either by:
* Finding (or requesting) the actual style guidelines for these tools (and adapting them as needed)
* Reverse engineering guidelines based on observation of these tools

![grafana-dashboard-example](https://user-images.githubusercontent.com/28311615/95880747-d907be80-0d45-11eb-8037-0ba6fd3bca50.PNG)
![vscode-editor-example](https://user-images.githubusercontent.com/28311615/95880786-e2912680-0d45-11eb-9a15-709b306ab3c5.PNG)

If reverse engineering guidelines, the tag colours in the [Grafana live demo](https://play.grafana.org/) dashboard management could be a good place to get an idea of the colour palette used:

![grafana-tag-colours](https://user-images.githubusercontent.com/28311615/95879734-b032f980-0d44-11eb-9e64-e59acb77f890.gif)

# Content
Style guidelines could be structured as:
* **Checklist:** Concise, well structured, quick to refer to. The main working tool for people who are familiar with the guidelines.
* **Accompanying document:** More detailed expression of certain checklist items (context, theoretical background, etc.) Read by those new to the guidelines or for reference as needed.

![guidelines-structure](https://user-images.githubusercontent.com/28311615/95884487-2e45cf00-0d4a-11eb-9200-1e266a21167d.PNG)

**Include good and bad examples** to illustrate the principles. Example pictures are often best (rather than text explanations).

**Could also include subjective or human checks** (ex. Does it feel visually intimidating? Do you feel invited to explore?). High-level user-focused questions can act as sanity checks. They can help avoid tunnel vision by encouraging devs to think about the project from a different perspective.

Contributor guide

Open the contributing guide

Research direction

Start with the prerequisite chart style guidelines issue #152, then review the VS Code and Grafana examples and the linked Grafana live demo for reusable principles. Done means documenting project-wide style principles as a concise checklist with an accompanying explanation, good and bad examples, and any human-focused checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
grafana, vscode
Domain
design, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.