New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[EZP-29121] Added UI Guidelines to documentation, basic structure #298

Merged
merged 6 commits into from Jun 29, 2018

Conversation

5 participants
@inakijv
Contributor

inakijv commented Jun 4, 2018

Question Answer
JIRA Ticket EZP-29121
Versions 2.2

Most important aspects:
Added UI Guidelines to documentation, basic structure:

  • Design Principles section: Design principles, Philosophy and Accessibility;
  • Resources section: Typography, Colors and Icons;
  • Resources section: buttons component (basic buttons).

design principles - ez platform developer documentation
typography - ez platform developer documentation
colors - ez platform developer documentation
icons - ez platform developer documentation 1
buttons - ez platform developer documentation 1

@inakijv

This comment has been minimized.

Contributor

inakijv commented Jun 4, 2018

Ping @DominikaK

@damianz5

This comment has been minimized.

Member

damianz5 commented Jun 4, 2018

mdx_ez_code_example should be moved to github ezsystems namespace, besides that looks great! 🥇 💥
ping @SylvainGuittard what do you think?

@@ -0,0 +1,7 @@
# User Interface Guidelines
<div class="mgt-3 mgb-1">This is a resource for developers, product managers, and designers, providing a unified language to build and customize eZ Platform admin user interface (aka Platform UI). We use it to simplify how we can build and offer a consistent interface across our content management platform.</div>

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

Is the div with styling necessary here?
Also, we don't use Platform UI in v2 anymore, AFAIK, it's either Admin UI or Back Office.

<div class="mgt-3 mgb-1">This is a resource for developers, product managers, and designers, providing a unified language to build and customize eZ Platform admin user interface (aka Platform UI). We use it to simplify how we can build and offer a consistent interface across our content management platform.</div>
eZ’s UI Guidelines provides a simplified and recognizable experience; increases our productivity, enabling us to evolve faster; and it allows us to develop collectively.

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

UI Guidelines provide, then increase and they allow

@@ -0,0 +1,33 @@
# Buttons
We use button as main element for click function. Use a disabled attribute disabled="disabled" when a button can’t be clicked.

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

You can put disabled="disabled" in backticks to format is as monospace, we do it for most directly quoted pieces of code.

@@ -0,0 +1,17 @@
## <div class="mgt-2">Overview and limitations</div>
<div class="mgt-minus-4">The overall accessibility of any project built with eZ Platform CMS depends in large part on the author’s markup, additional styling, and scripting they’ve included. However, provided that these have been implemented correctly, it should be perfectly possible to create websites and applications with Bootstrap that fulfill WCAG 2.0 (A/AA/AAA), Section 508 and similar accessibility standards and requirements.</div>

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

I'd get rid of CMS and simply use eZ Platform by itself

@@ -0,0 +1,17 @@
## <div class="mgt-2">Overview and limitations</div>

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

Again, is there any specific need for the HTML tags?

Also, it would be good to add a # Accessibility heading at the beginning for consistency

@@ -0,0 +1,194 @@
# Colors
Visual hierarchy and differentiation. We prioritize Create and Edit content as main functions in our CMS with orange color. Because most of the application has soft colors, color stands out and catches user's attention. We also define secondary, neutral and negative colors. Despite of this, it is also important to remind to not always rely on color to provide visual differentiation. If too many colors are employed, colors might lose their meaning.

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

These three paragraphs are the same as in the accessibility page. Is there any way to avoid the repetition?

**Typographic elements do not come with any other styling properties attached** to them in order to emphasize modularity and make them more flexible in where they can be used. If you need to add more styling properties don’t forget to look for any other component before.
We have selected <code>Noto Sans</code> due to it's intended to be visually harmonious across multiple languages, a priority for us when promoting a multilanguage platform.

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

Use backticks instead of <code> tags.
Also, due to the fact that it's intended

mkdocs.yml Outdated
@@ -3,6 +3,18 @@ repo_url: https://github.com/ezsystems/developer-documentation
copyright: "Copyright 1999-2017 eZ Systems AS and others"
pages:
- 'Documentation': 'index.md'
- UI Guidelines:

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

I'm not sure about the placement. I think this would go better under "Resources and community" (with the same internal structure)

mkdocs.yml Outdated
@@ -3,6 +3,18 @@ repo_url: https://github.com/ezsystems/developer-documentation
copyright: "Copyright 1999-2017 eZ Systems AS and others"
pages:
- 'Documentation': 'index.md'
- UI Guidelines:
- 'Introduction': 'guidelines/Introduction.md'

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

For consistency, it would be good to change all files names to lowercase.

@@ -0,0 +1,31 @@
The design philosophy underpins everything we do as a Product and Engineering Teams. It informs the way our products look, the way they behave and the way we work as a team.

This comment has been minimized.

@DominikaK

DominikaK Jun 4, 2018

Contributor

And missing heading again: # Philosophy

@inakijv inakijv force-pushed the inakijv:guidelines-test branch from 4f4b8a3 to 0bec0d4 Jun 4, 2018

@inakijv

This comment has been minimized.

Contributor

inakijv commented Jun 4, 2018

@DominikaK updated based on comments. Thanks!

@SylvainGuittard

This comment has been minimized.

SylvainGuittard commented Jun 4, 2018

mdx_ez_code_example should be moved to github ezsystems namespace, besides that looks great!
@damianz5 I totally agree.

@DominikaK

This comment has been minimized.

Contributor

DominikaK commented Jun 13, 2018

@inakijv, I adapted the text to fit better with the style of the rest of the dev doc. Please take a look to make sure that didn't twist your meaning.

Also, with the styling of headings there's a small problem with how markdown renders the links:
guidelines_brken_headings

That's a small thing, but maybe @damianz5 has an idea how to fix it?

@inakijv inakijv force-pushed the inakijv:guidelines-test branch from 3b8b42b to 0cdd02a Jun 13, 2018

@inakijv

This comment has been minimized.

Contributor

inakijv commented Jun 13, 2018

@DominikaK thank you. Updated based on discussed last week. I need a final clear on this :-) and ask engineers for their feedback. Thanks!

@inakijv inakijv force-pushed the inakijv:guidelines-test branch from 8d34398 to 8f4d452 Jun 25, 2018

@sunpietro

This comment has been minimized.

Member

sunpietro commented Jun 26, 2018

Why is it so big? I'd prefer making smaller changes in a multiple PRs

@sunpietro

This comment has been minimized.

Member

sunpietro commented Jun 26, 2018

Another question: do you use Bootstrap 3 and Bootstrap 4 on the same website? It's going to be a maintainance hell. As far as I know, our examples need Bootstrap 4, but the guideline is built with Bootstrap 3, right? So why didn't you display our code samples in iframes? It would separate the environments perfectly. No need to prefix Bootstrap, no naming conventions collisions.

@inakijv

This comment has been minimized.

Contributor

inakijv commented Jun 26, 2018

@sunpietro answering to your questions:

  • MKDOCs still uses Bootstrap 3, and we have had to find a solution combining both. Among all options discussed, this one was the most suitable for the needs we had;
  • Regarding the length of the PR, it sets the basic structure for this section (Components, Resources, Design principles) within Documentation site. I am more than happy to discuss any other aspects regarding the structure or the content (actually I believe it would be terrific);
  • The PRs will be smaller from now on due to they are going to be focused on each of the basic UI components, your input guys is really valuable for the Buttons section, for instance, due to the developer perspective that needs to be included here.

We are building a set of UI components, that is also a three-way collaboration (doc, engineering and pm teams) that needs to include all these views.

@sunpietro

This comment has been minimized.

Member

sunpietro commented Jun 26, 2018

@inakijv what about using iframes to display demo samples?

@damianz5

This comment has been minimized.

Member

damianz5 commented Jun 26, 2018

mkdocs-material is not using bootstrap in any version (https://squidfunk.github.io/mkdocs-material/),
iframes are not supported by mkdocs (mkdocs/mkdocs#1246), mkdocs will not generate partials, only the pages listed in mkdocs.yml.
Search engine will not be able to find and index content inside iframes - we will not be able to search

@sunpietro

This comment has been minimized.

Member

sunpietro commented Jun 26, 2018

So this is a dirty, but the only working way. I see.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment