diff --git a/docs/style_sheets.md b/docs/style_sheets.md index 78281fd34..f88608c91 100644 --- a/docs/style_sheets.md +++ b/docs/style_sheets.md @@ -1,19 +1,23 @@ # Style Sheets -Since Gaphor 2.0, Gaphor diagrams can have a different look by means of style sheets. -Style sheets use Cascading Style Sheets (CSS) syntax. -CSS is most known for it's application in web pages (HTML). +Since Gaphor 2.0, Gaphor diagrams can have a different look by means of style +sheets. Style sheets use the Cascading Style Sheets (CSS) syntax. CSS is used +to describe the presentation of a document written in a markup language, and is +most commonly used with HTML for web pages. -On the [W3C CSS home page](https://www.w3.org/Style/CSS/Overview.en.html), CSS is described as: +On the [W3C CSS home page](https://www.w3.org/Style/CSS/Overview.en.html), CSS +is described as: -> Cascading Style Sheets (CSS) is a simple mechanism for adding style (e.g., fonts, colors, spacing) to Web documents. +> Cascading Style Sheets (CSS) is a simple mechanism for adding style (e.g., +fonts, colors, spacing) to Web documents. -It's application goes well beyond web documents, though. -Gaphor uses CSS to provide style elements to items in diagrams. -CSS allows us, users of Gaphor, to change the visual appearance of our diagrams. -Color and line styles can be changed to make it easier to read the diagrams. +Its application goes well beyond web documents, though. Gaphor uses CSS to +provide style elements to items in diagrams. CSS allows us, users of Gaphor, to +change the visual appearance of our diagrams. Color and line styles can be +changed to make it easier to read the diagrams. -Since we're dealing with a diagram, and not a HTML document, some CSS features have been left out. +Since we're dealing with a diagram, and not a HTML document, some CSS features +have been left out. The style is part of the model, so everyone working on a model will have the same style. @@ -34,8 +38,8 @@ node component { } ``` -The diagram itself is also expressed as a CSS node. -It's pretty easy to define a "dark" style: +The diagram itself is also expressed as a CSS node. It's pretty easy to define +a "dark" style: ``` css diagram { @@ -48,15 +52,14 @@ diagram { } ``` -Here you already see the first custom attribute: `text-color`. -This property allows you to control the color of the text drawn in an item. -`color` is used for the lines (strokes) that make the layout of a diagram item. +Here you already see the first custom attribute: `text-color`. This property +allows you to control the color of the text drawn in an item. `color` is used +for the lines (strokes) that make the layout of a diagram item. ## Supported selectors -We're dealing with diagrams, models. -Therefore we do not need all features of CSS. -Below you'll find a summation of all CSS features supported by Gaphor. +Since we are dealing with diagrams and models, we do not need all the features +of CSS. Below you'll find a summary of all CSS features supported by Gaphor. ```eval_rst ============================= ============================ @@ -72,19 +75,19 @@ Below you'll find a summation of all CSS features supported by Gaphor. ``diagram[name|=draft]`` A diagram with a name is "draft" or starts with "draft-". ``\*:focus`` The focused item. Other pseudo classes are: - - ``:active`` selected items; - - ``:hover`` for the item under the mouse; - - ``:drop`` if an item is draggen and can be dropped on this item. + - ``:active`` selected items + - ``:hover`` for the item under the mouse + - ``:drop`` if an item is dragged and can be dropped on this item ``node:empty`` A node containing no child nodes in the diagram. ``:root`` An item is at the top level of the diagram. This is only applicable for the diagram -``:has()`` The item has contains any of the provided selectors. +``:has()`` The item contains any of the provided selectors. E.g. ``node:has(component)``: a node containing a component item. ``:is()`` Match any of the provided selectors. - E.g. ``:is(node, subsystem) > component``: a node or synsystem. + E.g. ``:is(node, subsystem) > component``: a node or subsystem. ``:not()`` Negate the selector. E.g. ``:not([subject])``: Any item that has no "subject". @@ -92,18 +95,19 @@ Below you'll find a summation of all CSS features supported by Gaphor. ``` * The official specification of [CSS3 attribute selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#attribute-selectors). -* The `|=` attribute selector is provided for the sake of completeness. It's probably not very useful in a Gaphor context. -* Please note that Gaphor CSS does not support ID's for diagram items, - so the CSS syntax for id's (`#some-id`) is not used. - Also class syntax (`.some-class`) is not supported. +* We provide the `|=` attribute selector for the sake of completeness. It's + probably not very useful in a Gaphor context. +* Please note that Gaphor CSS does not support IDs for diagram items, so the + CSS syntax for IDs (`#some-id`) is not used. Also, class syntax + (`.some-class`) is not supported. ## Style properties Gaphor supports a subset of CSS properties and some Gaphor specific properties. -The style sheet interpreter is relatively straight forward. -All widths, heights and sizes are measured in pixels. -No complex style declarations are supported, -like the `font` property in HTML/CSS which can contain font family, size, weight. +The style sheet interpreter is relatively straight forward. We measure all +widths, heights, and sizes in pixels. We don't support complex style +declarations, like the `font` property in HTML/CSS which can contain font +family, size, weight. ### Colors @@ -125,69 +129,73 @@ like the `font` property in HTML/CSS which can contain font family, size, weight ``` * A color can be any [CSS3 color code](https://www.w3.org/TR/2018/REC-css-color-3-20180619/), - as described in the CSS documentation. - All color notations are supported: `rgb()`, `rgba()`, `hsl()`, `hsla()`, Hex code (`#ffffff`) and color names. + as described in the CSS documentation. We support all color notations: + `rgb()`, `rgba()`, `hsl()`, `hsla()`, Hex code (`#ffffff`) and color names. ### Text and fonts ```eval_rst ======================= ======================================= ``font-family`` A single font name (e.g. ``sans``, ``serif``, ``courier``) -``font-size`` Font size: ``font-size: 14``. +``font-size`` Font size: ``font-size: 14`` ``font-style`` Either ``normal`` or ``italic`` ``font-weight`` Either ``normal`` or ``bold`` ``text-align`` Either ``left``, ``center``, ``right`` ``text-decoration`` Either ``none`` or ``underline`` -``vertical-align`` Vertical alignment for text. +``vertical-align`` Vertical alignment for text - Either ``top``, ``middle`` or ``bottom``. -``vertical-spacing`` Set vertical spacing for icon-like items (actors, start state). + Either ``top``, ``middle`` or ``bottom`` +``vertical-spacing`` Set vertical spacing for icon-like items (actors, start state) Example: ``vertical-spacing: 4`` ======================= ======================================= ``` -* `font-family` can be only one font name, not a list of (fallback) names, as is used for HTML. +* `font-family` can be only one font name, not a list of (fallback) names, as + is used for HTML. ### Drawing and spacing ```eval_rst ======================= ======================================= -``border-radius`` Radius for rectangles: ``border-radius: 4``. -``dash-style`` Style for dashed lines: ``dash-style: 7 5``. -``line-style`` Either ``normal`` or ``sloppy [factor]``. -``line-width`` Set the width for lines: ``line-width: 2``. -``min-height`` Set minimal height for an item: ``min-height: 50``. -``min-width`` Set minimal width for an item: ``min-width: 100``. -``padding`` CSS style padding (top, right, bottom, left). +``border-radius`` Radius for rectangles: ``border-radius: 4`` +``dash-style`` Style for dashed lines: ``dash-style: 7 5`` +``line-style`` Either ``normal`` or ``sloppy [factor]`` +``line-width`` Set the width for lines: ``line-width: 2`` +``min-height`` Set minimal height for an item: ``min-height: 50`` +``min-width`` Set minimal width for an item: ``min-width: 100`` +``padding`` CSS style padding (top, right, bottom, left) Example: ``padding: 3 4`` ======================= ======================================= ``` -* `padding` is defined by 1 to 4 numbers. No unit (px, pt, em) needs to be used. All values are in pixel distance. +* `padding` is defined by integers in the range of 1 to 4. No unit (px, pt, em) + needs to be used. All values are in pixel distance. * `dash-style` is a list of numbers (line, gap, line, gap, ...) -* `line-style` has only effect when defined on a `diagram`. A sloppiness factor can be provided, somewhere between -2 and 2. +* `line-style` only has an effect when defined on a `diagram`. A sloppiness + factor can be provided in the range of -2 to 2. ### Diagram styles Only a few properties can be defined on a diagram, namely `background-color` -and `line-style`. The diagram style is defined separately from the diagram item +and `line-style`. We define the diagram style separately from the diagram item styles. That way it's possible to set the background color for diagrams -specifically. The line style can be normal, straight, lines or a more playful -"sloppy" style. For the sloppy style an optional factor can be provided. This -factor determines the level of wobblyness of the lines. 0.5 is default, 0.0 is -a straight line. The value should be between -2.0 and 2.0. Values between 0.0 -and 0.5 make for a subtle effect. +specifically. The line style can be the normal straight lines, or a more +playful "sloppy" style. For the sloppy style an optional wobliness factor can +be provided to set the level of line wobbliness. 0.5 is default, 0.0 is a +straight line. The value should be between -2.0 and 2.0. Values between 0.0 and +0.5 make for a subtle effect. ## Ideas -Here are some ideas that go just beyond changing a color or a font. -With the following examples we dig in to Gaphor's model structure to reveal more +Here are some ideas that go just beyond changing a color or a font. With the +following examples we dig in to Gaphor's model structure to reveal more information to the users. -To create your own expression you may want to use the Console (Tools -> Console, in the Hamburger ment). -Drop us a line on [Gitter](https://gitter.im/gaphor/Lobby) and we're happy to help you. +To create your own expression you may want to use the Console (Tools -> +Console, in the Hamburger menu). Drop us a line on +[Gitter](https://gitter.im/gaphor/Lobby) and we would be happy to help you. ### The drafts package @@ -201,10 +209,12 @@ diagram[namespace.name=drafts] { ### Unconnected relationships -All items on a diagram that are not backed by a model element, should be drawn in a dark red color. -This can be used to spot not-so-well connected relationships, such as Generalization, Implementation, and Dependency. -These items will only be backed by a model element once both line ends are connected. -This rule will exclude simple elements line lines and boxes, which will never have a backing model element. +All items on a diagram that are not backed by a model element, should be drawn +in a dark red color. This can be used to spot not-so-well connected +relationships, such as Generalization, Implementation, and Dependency. +These items will only be backed by a model element once you connect both line +ends. This rule will exclude simple elements, like lines and boxes, which will +never have a backing model element. ```css :not([subject], :is(line, box, ellipse, commentline)) { @@ -214,9 +224,11 @@ This rule will exclude simple elements line lines and boxes, which will never ha ### Navigable associations -Say you create a model and for some reason at least one end should be navigable. -This is actually the case for the model file used to create Gaphor's data model. -If no end is navigable I'd like to signal this by coloring the association blue. +An example of how to apply a style to a navigable association is to color an +association blue if neither of the ends are navigable. This color could act as +a validation rule for a model where at least one end of each association should +be navigable. This is actually the case for the model file used to create +Gaphor's data model. ```css association:not([memberEnd.navigability*=true]) {